Комментарии Javadoc тоже бывают «шумовыми». Какую пользу приносят следующие комментарии (из хорошо известной библиотеки, распространяемой с открытым кодом)? Ответ: никакой. Это избыточные шумовые комментарии, вызванные неуместным желанием как-то документировать свои действия.
>/** Имя. */
>private String name;
>/** Версия. */
>private String version;
>/** Название лицензии. */
>private String licenceName;
>/** Версия. */
>private String info;
Прочитайте эти комментарии повнимательнее. Заметили ошибку копирования/вставки? Если авторы не следят за ними в момент написания (или вставки), то как можно ожидать, что эти комментарии принесут пользу читателю?
Не используйте комментарии там, где можно использовать функцию или переменную
Возьмем следующий фрагмент кода:
>// Зависит ли модуль из глобального списка от подсистемы,
>// частью которой является наш код?
>if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
Его можно было бы перефразировать без комментария в следующем виде:
>ArrayList moduleDependees = smodule.getDependSubsystems();
>String ourSubSystem = subSysMod.getSubSystem();
>if (moduleDependees.contains(ourSubSystem))
Возможно (хотя и маловероятно), автор исходного кода сначала написал комментарий, а затем — соответствующий ему код. Но после этого автор должен был переработать свой код, как это сделал я, чтобы комментарий можно было удалить.
Некоторые программисты любят отмечать определенные позиции в исходных файлах. Например, недавно я обнаружил в одной из просматриваемых программ следующую строку:
>// Действия //////////////////////////////////
В отдельных случаях объединение функций под такими заголовками имеет смысл. Но в общем случае они составляют балласт, от которого следует избавиться — особенно от назойливой серии косых черт в конце.
Взгляните на дело под таким углом: заголовки привлекают внимание только в том случае, если они встречаются не слишком часто. Используйте их умеренно и только тогда, когда они приносят ощутимую пользу. При слишком частом употреблении заголовков читатель воспринимает их как фоновый шум и перестает обращать на них внимание.
Комментарии за закрывающей фигурной скобкой
Иногда программисты размещают специальные комментарии за закрывающими фигурными скобками, как в листинге 4.6. Применение таких комментариев оправдано в длинных функциях с многоуровневой вложенностью, но они только загромождают компактные специализированные функции, которым мы отдает предпочтение. Итак, если у вас возникает желание прокомментировать закрывающие фигурные скобки, лучше постарайтесь укоротить свои функции.