17/97: Комментируйте только то, что не говорит сам код

Это перевод Comment Only What the Code Cannot Say. Автор: Kevlin Henney.

Из "97-ми вещей, которые должен знать каждый программист".

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

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

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

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

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