97 этюдов для программистов. Опыт ведущих экспертов

Комментируйте только то, о чем не скажет код Кевлин Хенни

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

Если код написан с нарушениями синтаксиса, то компиляторы, интерпретаторы и другие средства разработки обязательно воспротивятся. Если код некорректен с функциональной точки зрения, большая часть ошибок выявится в результате рецензирования, статического анализа, тестирования и боевого применения на коммерческом предприятии. А что с комментариями? В книге «The Elements of Programming Style»[7] (Computing McGraw-Hill) Керниган и Плоджер замечают, что «неверный комментарий имеет нулевое или отрицательное значение». И все же такие негодные комментарии успешно приживаются в коде на зависть ошибкам всех видов. Они постоянно отвлекают внимание и дезинформируют. Они служат незаметным, но постоянно действующим тормозом мышления программиста.

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

Засилье в коде бессодержательных и неправильных комментариев провоцирует программистов попросту игнорировать все комментарии, пропуская их при чтении либо выключая их отображение. Программисты — люди изобретательные, и найдут способы обойти все, что покажется им вредоносным: свернут комментарии, изменят цветовую схему так, чтобы комментарии были одного цвета с фоном, или удалят комментарии специально написанным сценарием. Чтобы спасти код от такого неуместного приложения творческих способностей программистов и чтобы снизить риск того, что кто-то пропустит действительно ценные комментарии, следует считать комментарии частью кода. Каждый комментарий должен иметь какую-то ценность для читателя, иначе это просто мусор, который нужно убрать или переработать.

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