Комментируйте лишь то, что не ясно из кода

(В оригинале - Comment Only What the Code Cannot Say)

Различий между теорией и практикой гораздо больше на практике, чем в теории – это как нельзя более актуально применительно к комментариям. В теории идея комментариев заключается в том, чтобы «объяснить то, что происходит, дать больше деталей». Чем же желание объяснить может быть плохим? Однако на практике комментарии часто начинают приносить вред, а не пользу. Как и в любом другом деле, написание хороших комментариев – это умение. И значительная часть умения состоит в том, чтобы знать, когда их вообще писать не надо.

Если в коде есть ошибки, то компилятор, интерпретатор или другой подобный инструмент это сразу же обнаружат. Если ошибки есть на функциональном уровне, то ревью, статический анализ, тестирование и эксплуатация рано или поздно будут приводить к их обнаружению и устранению. А комментарии? В книге “The Elements of Programming Style” Kernighan и Plauger заметили, что «комментарий имеет нулевую или отрицательную ценность, если он неправильный». И такие комментарии часто сильно засоряют исходный код, оставаясь там долгое время, в отличие от ошибок в самом коде. При этом такие комментарии постоянно приводят к отвлечению внимания или даже к дезориентации того, кто этот код сопровождает.

А что, если комментарий не является технически неправильным, а лишь не приносит дополнительной ценности? Такие комментарии – это шум. Комментарий, повторяющий код, не дает читателю никакой дополнительной информации – повторение одного и того же сначала на языке программирования, а потом на человеческом не делает код более понятным. Закоментированный кусок кода не выполняется, поэтому не несет ничего интересного ни во время выполнения, ни для изучающего код. К тому же такой код очень быстро устаревает. Система контроля версий делает то, для чего предполагалось оставить закомментированный код, а именно отслеживание изменений, гораздо лучше.

Обилие «шумовых» и вообще неправильных комментариев в коде приводит лишь к игнорированию комментариев вообще. Программист легко может сделать что-нибудь, что может повлечь реальную проблему – игнорирование действительно важного комментария: спрятать все комментарии, настроить IDE так, чтоб комментарии отображались цветом фона, удалить все комментарии при помощи скрипта или еще что-нибудь подобное. И чтобы предотвратить такой сценарий, к комментариям надо относиться так, словно это не комментарий, а код. Любой комментарий должен иметь свою собственную ценность для читателя, в противном случае его не надо писать вообще, удалить написанный или же переписать заново.

Что же считать ценностью? Комментарий должен сообщать что-то, чего код не сообщает и не может сообщить. Желание написать комментарий, содержимое которого может быть видно из кода – это сигнал к изменению стиля кода так, чтобы код говорил сам за себя. Вместо объяснения непонятных имен функций, классов или полей, просто переименуйте их. Вместо комментирования секций длинной функции разбейте ее на несколько мелких и назовите их адекватными именами. Лишь то, что вы на самом деле не можете «сказать» в коде, является кандидатом на комментарий.

Комментируйте лишь то, что код не может сообщить в принципе, а не то, что он не сообщает сейчас.

Автор оригинала - Kevlin Henney