Как писать комментарии

Опять я почитала книгу С. Мартина "Чистый код. Создание, анализ, рефакторинг". Ниже привожу понравившиеся советы из книги по поводу написания комментариев.

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

2. Ясный и выразительный код с минимумом комментариев гораздо лучше громоздкого сложного кода с большим количеством комментариев. Не тратьте время на написание комментариев, объясняющих созданную вами путаницу. Лучше потратьте его на исправление кода. Например, с каким кодом вы бы предпочли работать:

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

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

4. Предупреждения о последствиях - это весьма полезные комментарии. Например:

5. Иногда бывает полезно оставить заметки на будущее в форме комментариев TODO. Регулярно просматривайте такие комментарии и удаляйте те, которые потеряли актуальность.

6. Комментарий может подчеркивать важность обстоятельства, которое на первый взгляд кажется несущественным:

7. Избыточные комментарии. Читаются не проще, чем сам код. Например:

А вот еще избыточные комментарии:

8.  Использовать штуки типа Javadoc - это хорошо. Но правила, говорящие, что каждая функция должна иметь комментарий Javadoc или что каждая переменная должна быть помечена комментарием - обычная глупость. Такие комментарии только загромождают код, распространяют недостоверную информацию и вызывают общую путаницу и дезориентацию. Например, вот тут комментарий совершенно избыточен:

При всей полезности комментариев Javadoc для API общего пользования не применяйте их в коде, не предназначенном для общего потребления. 

9. Позиционные маркеры. Это строки типа:

//Действия///////////////

В отдельных случаях объединение функций под такими заголовками имеет смысл. Но в общем случае они составляют балласт, от которого следует избавиться - особенно от назойливой серии косых черт в конце. Взгляните на дело под таким углом: заголовки привлекают внимание только в том случае, если они встречаются не слишком часто.

10. В программировании редко встречаются привычки более отвратительные, чем закрытие комментариями неиспользуемого кода. Никогда не делайте этого! У других программистов, видящих закомментированный код, не хватает храбрости удалить его. Они полагают, что код оставлен не зря и слишком важен для удаления. В итоге закомментированный код скапливается, словно осадок на дне бутылки плохого вина. Системы контроля исходного кода запоминают изменения в коде за нас.

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

12. Плохо, когда сам комментарий нуждается в объяснениях. Например, (см. ниже) - что такое байты фильтра? Они как-то связаны с +1 или *3? Один пиксел соответствует одному байту?