Лучшая практика для комментариев в исходных файлах Java?

Question

Это не не имеет , чтобы быть Java, но это то, с чем я имею дело. Кроме того, меня не интересуют методы и их детали, мне интересно узнать общий файл класса.

Что мне действительно нужно иметь в моих комментариях для данного файла класса? В моей корпорации, единственное, что я действительно могу придумать:

• Copyright / Лицензия
• Описание того, что делает класс
• Дата последнего изменения?

Есть ли что-нибудь еще, что следует предоставить?

Одна логическая вещь, которую я слышал, это не допускать авторов в заголовок, поскольку она избыточна, поскольку информация уже предоставляется через систему контроля версий.

Обновление: Здесь можно предположить JavaDoc, но я действительно больше обеспокоен деталями того, что полезно включать в отношении контента, будь то окончательные метаданные, которые можно добывать, или более свободные, ПОЧЕМУ и т. Д. ...

Answer 1

Одна логическая вещь, которую я слышал, это не допускать авторов в заголовок, потому что это избыточно с информацией, уже предоставленной через контроль источника.

также дата последнего изменения избыточна

Я использую небольшой набор шаблонов документации :

• всегда документирует безопасность потоков
• всегда документирует неизменность
• javadoc с примерами
• @ Устаревание с ПОЧЕМУ и КАК для замены аннотированного элемента
• сохранение комментариев как минимум

Answer 2

Нет «последней измененной дате» - это тоже относится к управлению исходным кодом.

Два других в порядке. В основном сконцентрируйтесь на полезном тексте - что делает класс, любые предостережения относительно безопасности потоков, ожидаемое использование и т. Д.

Комментарии к реализации обычно должны быть о том, почему вы делаете что-то неочевидное, и поэтому должны быть редкими. (Например, это может быть из-за того, что некоторые API ведут себя необычным образом, или потому что есть полезный ярлык, который вы можете использовать, но который не сразу очевиден.)

Answer 3

Когда вы чувствуете необходимость писать комментарии для объяснения того, что делает какой-то код, улучшите читабельность кода, чтобы комментарии не были нужны. Вы можете сделать это, переименовав методы / поля / классы, чтобы иметь больше значимых имен , и разделив более крупные методы на более мелкие методы, используя шаблон составного метода .

Если даже после всех ваших усилий код не говорит само за себя, например, причина почему какой-то неочевидный код должен был быть написан, неясно из кода, тогда извинитесь, написав комментарии . (Иногда вы можете задокументировать причины, написав тест, который завершится неудачей, если кто-то изменит неочевидный, но правильный код, чтобы сделать очевидную, но неправильную вещь. Но в дополнение к этому комментарий также полезен. Я ставлю такой префикс комментарии часто с "// HACK:" или "// XXX:".)

Answer 4

Для здравомыслия себя и будущих разработчиков, вам действительно следует написать Javadocs .

Answer 5

Если вы назначаете владение компонентами конкретным разработчикам или командам, их владельцы должны записываться в источнике компонента или метаданных VCS.

Answer 6

Общее описание назначения класса, описание для каждого поля и контракт для каждого метода. Формат Javadoc работает хорошо.