Опять я почитала книгу С. Мартина "Чистый код. Создание, анализ, рефакторинг". Ниже привожу понравившиеся советы из книги по поводу написания комментариев.
1. Программисты не могут нормально совпровождать комментарии. Программный код изменяется и эволюционирует. Его фрамгенты перемещаются из одного места в другое, размножаются и сливаются. Слишком часто комментарии отделяются от описываемого ими кода и превращаются в пометки непонятной принадлежности с постоянно снижающейся точностью. Неточные комментарии гораздо вреднее, чем отсутствие комментариев. Они обманывают и сбивают с толку программиста, создают у него невыполненные ожидания.
2. Ясный и выразительный код с минимумом комментариев гораздо лучше громоздкого сложного кода с большим количеством комментариев. Не тратьте время на написание комментариев, объясняющих созданную вами путаницу. Лучше потратьте его на исправление кода. Например, с каким кодом вы бы предпочли работать:
5. Иногда бывает полезно оставить заметки на будущее в форме комментариев TODO. Регулярно просматривайте такие комментарии и удаляйте те, которые потеряли актуальность.
6. Комментарий может подчеркивать важность обстоятельства, которое на первый взгляд кажется несущественным:
1. Программисты не могут нормально совпровождать комментарии. Программный код изменяется и эволюционирует. Его фрамгенты перемещаются из одного места в другое, размножаются и сливаются. Слишком часто комментарии отделяются от описываемого ими кода и превращаются в пометки непонятной принадлежности с постоянно снижающейся точностью. Неточные комментарии гораздо вреднее, чем отсутствие комментариев. Они обманывают и сбивают с толку программиста, создают у него невыполненные ожидания.
2. Ясный и выразительный код с минимумом комментариев гораздо лучше громоздкого сложного кода с большим количеством комментариев. Не тратьте время на написание комментариев, объясняющих созданную вами путаницу. Лучше потратьте его на исправление кода. Например, с каким кодом вы бы предпочли работать:
Зачастую задача сводится к созданию функции, чье название сообщает то же самое, что и комментарий, который вы собирались написать.
3. Юридические комментарии - например, заявление об авторских правах. Такие комментарии не должны представлять собой трактаты. Вместо того, чтобы перечислять в комментарии все условия, по возможности ограничьтесь ссылкой на стандартную лицензию или другой внешний документ.
4. Предупреждения о последствиях - это весьма полезные комментарии. Например:
6. Комментарий может подчеркивать важность обстоятельства, которое на первый взгляд кажется несущественным:
7. Избыточные комментарии. Читаются не проще, чем сам код. Например:
А вот еще избыточные комментарии:
8. Использовать штуки типа Javadoc - это хорошо. Но правила, говорящие, что каждая функция должна иметь комментарий Javadoc или что каждая переменная должна быть помечена комментарием - обычная глупость. Такие комментарии только загромождают код, распространяют недостоверную информацию и вызывают общую путаницу и дезориентацию. Например, вот тут комментарий совершенно избыточен:
При всей полезности комментариев Javadoc для API общего пользования не применяйте их в коде, не предназначенном для общего потребления.
9. Позиционные маркеры. Это строки типа:
//Действия///////////////
В отдельных случаях объединение функций под такими заголовками имеет смысл. Но в общем случае они составляют балласт, от которого следует избавиться - особенно от назойливой серии косых черт в конце. Взгляните на дело под таким углом: заголовки привлекают внимание только в том случае, если они встречаются не слишком часто.
10. В программировании редко встречаются привычки более отвратительные, чем закрытие комментариями неиспользуемого кода. Никогда не делайте этого! У других программистов, видящих закомментированный код, не хватает храбрости удалить его. Они полагают, что код оставлен не зря и слишком важен для удаления. В итоге закомментированный код скапливается, словно осадок на дне бутылки плохого вина. Системы контроля исходного кода запоминают изменения в коде за нас.
11. Не излагайте информацию системного уровня в контексте локального комментария. Примером служит следующий комментарий. Не считая того, что он избыточен, в него также включена информация о порте по умолчанию, при том, что функция никоим образом не может управлять этим значением. И конечно, ничто не гарантирует, что комментарий будет изменен при изменении кода, в котором это значение определяется.
12. Плохо, когда сам комментарий нуждается в объяснениях. Например, (см. ниже) - что такое байты фильтра? Они как-то связаны с +1 или *3? Один пиксел соответствует одному байту?