Комментарий в нужном месте

В этой главе мы заняты в основном комментированием кода –тем, что мы фактически вводим в исходный код. Но по соседству бродят комментарии других видов:

Комментарии системы управления версиями

В системе управления версиями хранится история модификаций каждого файла за время су-ществования проекта. Она связывает с каждой версией определенные метаданные – во

всяком случае комментарии программиста, сделанные им при сохранении версии.Кроме того, могут записываться комментарии, сделанные при загрузке, если ведется учет файлов,

находящихся в данное время в работе. В этих комментариях можно описать, что вы собира-етесь изменить.

Такие комментарии очень ценны, и их нужно тщательно составлять. Они должны быть:

• Краткими (для быстроты просмотра журнала модификаций)

• Точными (не ошибитесь, иначе труд бесполезен)

• Полными (чтобы знать обо всех изменениях, не прибегая к сравнению версий вручную с помощью diff)

Регистрируйте, что было изменено и по какой причине, а не как было изменено. О том, какие изменения сделаны, можно узнать, сравнив версии.

В заголовке не должно быть информации, которая может быстро устареть, такой как сведения об авторах, модификаторах и дате последней модификации. Вряд ли ее станут часто обнов-лять, и она станет неверной. Эти сведения вам должна сообщить система контроля версий. Не нужно также излагать историю создания файла, описывающую все проведенные с ним модификации. Эти данные есть в системе контроля версий, и дублировать их здесь не нужно. Кроме того, если для того чтобы добраться до первой строки кода, нужно прокрутить 10 страниц истории модификаций, работать с файлом становится утомительно.

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

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

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

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

Распространенный подход к написанию программы – сначала смоделировать ее структуру в комментариях, а потом написать код под каждой строчкой комментария. Если вы работаете в таком стиле, то, закончив работу, спросите себя, по-прежнему ли вам нужны оставшиеся

Вот тут и место комментариям по поводу прошлого, а также ссылкам на систему контроля и исправления ошибок. Не поддавайтесь искушению поместить эти данные в комментарии

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

Файлы README

Эти обычные текстовые файлы, лежащие в тех же каталогах, что и файлы с исходным кодом. Это полезная документация, занимающая промежуточное положение между формальными спецификациями и комментариями в коде. Они часто содержат практическую информацию, например о том, каково назначение каждого файла или какова иерархия файлов;обычно это короткие заметки.

Файлы README часто составляются поспешно и непродуманно либо плохо сопровождаются и являются устаревшими, что недопустимо. Заметив файл README, естественно загрузить его и посмотреть, какая полезная информация в нем есть. Наличие файла README свиде-тельствует о том, что кто-то сознательно собрал вместе файлы с исходным кодом; нашлось нечто, достойное включения в документ и упоминания.

Оцените их в соответствии с обсуждавшимися здесь критериями и отредактируйте или удалите. Не двигайтесь дальше без проведения такой ревизии. Альтернатива – написать новую программу, а потом уже добавить нужные комментарии. Есть опасность забыть довести дело до конца или что комментарии, когда их пишешь, слишком хорошо зная код,

окажутся не лучшего качества. Опытный программист пишет комментарии в процессе работы. Практика показывает, какой объем комментариев оправдан.

Не бойтесь пользоваться флажками, типа рассмотренных выше TODO, в качестве пометок для самого себя. Это поможет вам не забыть ликвидировать досадные мелкие «хвосты». Такого рода комментарии легко обнаружить в коде и узнать, что еще требует доделки.