126 Глава 5. Заметки на полях

В заголовке не должно быть информации, которая может быстро уста%

реть, такой как сведения об авторах, модификаторах и дате последней

модификации. Вряд ли ее станут часто обновлять, и она станет невер%

ной. Эти сведения вам должна сообщить система контроля версий. Не

нужно также излагать историю создания файла, описывающую все

проведенные с ним модификации. Эти данные есть в системе контроля

версий, и дублировать их здесь не нужно. Кроме того, если для того

чтобы добраться до первой строки кода, нужно прокрутить 10 страниц

истории модификаций, работать с файлом становится утомительно.

По этой причине некоторые программисты помещают историю в конец

файла, но и в этом случае файл оказывается излишне велик, медленно

загружается и работать с ним обременительно.

Работа с комментариями

Комментариями удобно пользоваться при написании кода. Но не зло%

употребляйте ими.

Помощь при написании программ

Распространенный подход к написанию программы – сначала смоде%

лировать ее структуру в комментариях, а потом написать код под каж%

дой строчкой комментария. Если вы работаете в таком стиле, то, за%

кончив работу, спросите себя, по%прежнему ли вам нужны оставшиеся

Вот тут и место комментариям по поводу прошлого, а также

ссылкам на систему контроля и исправления ошибок. Не под%

давайтесь искушению поместить эти данные в комментарии

к исходному коду. Помните: один факт – один источник.

Файлы README

Эти обычные текстовые файлы, лежащие в тех же каталогах,

что и файлы с исходным кодом. Это полезная документация,

занимающая промежуточное положение между формальны%

ми спецификациями и комментариями в коде. Они часто со%

держат практическую информацию, например о том, каково

назначение каждого файла или какова иерархия файлов;

обычно это короткие заметки.

Файлы README часто составляются поспешно и непродуманно

либо плохо сопровождаются и являются устаревшими, что недо%

пустимо. Заметив файл README, естественно загрузить его

и посмотреть, какая полезная информация в нем есть. Наличие

файла README свидетельствует о том, что кто%то сознательно

собрал вместе файлы с исходным кодом; нашлось нечто, достой%

ное включения в документ и упоминания.

Работа с комментариями 127

комментарии. Оцените их в соответствии с обсуждавшимися здесь

критериями и отредактируйте или удалите. Не двигайтесь дальше без

проведения такой ревизии.

Альтернатива – написать новую программу, а потом уже добавить

нужные комментарии. Есть опасность забыть довести дело до конца

или что комментарии, когда их пишешь, слишком хорошо зная код,

окажутся не лучшего качества. Опытный программист пишет коммен%

тарии в процессе работы. Практика показывает, какой объем коммен%

тариев оправдан.

Не бойтесь пользоваться флажками, типа рассмотренных выше TODO,

в качестве пометок для самого себя. Это поможет вам не забыть ликви%

дировать досадные мелкие «хвосты». Такого рода комментарии легко

обнаружить в коде и узнать, что еще требует доделки.

Заметки об исправлении ошибок

Частая, но спорная практика – помещение заметок в местах, где ис%

правлены ошибки. Посреди какой%нибудь функции можно натолк%

нуться на комментарий такого типа:

// <ссылка на баг> заменено на метод blah.foo2()

// поскольку blah.foo() некорректно обрабатывал

// <некоторое условие>

blah.foo2();

Написанные с лучшими намерениями (чтобы помочь разобраться в слу%

чившемся во время разработки), эти комментарии часто приносят

больше вреда, чем пользы. Чтобы понять суть проблемы, вам придется

найти ошибку в системе учета ошибок и загрузить предыдущую вер%

сию файла, чтобы выяснить, какие изменения были внесены. Редкие

исправления ошибок нуждаются в такого рода работе, и новичку, воз%

можно, лучше остаться в блаженном неведении. Такие комментарии

на поздних стадиях разработки множатся в числе и при сопровожде%

нии засоряют исходный код побочными рассуждениями и устаревшей

информацией, отвлекают от главного потока исполнения.

В пользу помещения такого рода комментария может говорить неоче%

видность исправления – чтобы кто%то, работающий над кодом в буду%

щем, не вздумал вернуть прежнюю ошибку. Однако в таких исключи%

тельных случаях вы фактически документируете нетривиальное ме#

сто, а не размещаете сообщение об ошибке.

Комментарии должны касаться настоящего, а не прошлого. Не описывайте

того, что претерпело изменения, и не рассказывайте о том, как было раньше.

Устаревание комментариев

Комментарии разрушаются. Любой плохо сопровождаемый код подвер%

жен разрушению; в нем появляются неприглядные заплаты и теряется