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

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

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

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

Нет "дате последнего изменения" - это тоже относится к системе управления версиями.

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

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

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

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