Границы

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

основные разделы могут разграничиваться таким комментарием:

/********************************************************

* реализация класса foo

*********************************************************/

Некоторые программисты любят помещать большие художественные комментарии перед каждой функцией. Другие отчеркивают функции длинными однострочными комментариями. Я предпочитаю просто пару пустых строк перед каждой функцией. Если ваши функции такие

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

Флажки

Комментарии могут также использоваться в качестве встроенных флажков в коде. Есть ряд общепринятых соглашений. В файлах, работа над которыми не завершена, вы тут и там встретите //XXX, //FIXME (исправить) или //TODO (сделать). Хорошие редакторы с под-светкой синтаксиса могут выделять такие комментарии. XXX отмечает опасный или требу-ющий переработки код. TODO часто помечает отсутствие некоей функциональности, кото-рую в будущем нужно реализовать.FIXME указывает на фрагмент, в котором есть ошибки.

Комментарии в заголовке файла

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

программист чувствует доверие к содержимому файла; это свидетель С комментариями TODO будьте осторожны. Может быть, лучше генерировать исключение TODO, не заметить которое нельзя. В этом случае, если вы забудете реализовать отсутствующий код, ваша программа выйдет на за%

планированный отказ в работе.

Замечание об эстетичности 125

ство того, что файл создавался тщательно, а не является лишь черно%

виком некоего нового кода.

Снабжайте каждый файл исходного кода прологом в виде комментария.

Некоторые выступают за то, чтобы в этом заголовке был список всех

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

в данном файле. Но такой подход представляет катастрофу для сопро%

вождения: комментарий быстро оказывается устаревшим. В заголовке

файла уместно сообщить такие данные, как назначение файла (на%

пример, реализация интерфейса foo) и заявление об авторских пра%

вах, указывающее владельца и права копирования.

Если файл исходного кода автоматически создан в процессе сборки,

необходимо каким%либо образом включить в заголовок комментарий,

который четко информирует (БОЛЬШИМИ ПРОПИСНЫМИ БУКВА%

МИ) об источнике происхождения файла. Иначе кто%нибудь по ошиб%

ке станет его редактировать, не зная, что потеряет свой труд после оче%

редной сборки.

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

В этой главе мы заняты в основном комментированием кода –

тем, что мы фактически вводим в исходный код. Но по соседству

бродят комментарии других видов:

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

В системе управления версиями хранится история модифика%

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

связывает с каждой версией определенные метаданные – во

всяком случае комментарии программиста, сделанные им

при сохранении версии. Кроме того, могут записываться ком%

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

находящихся в данное время в работе. В этих комментариях

можно описать, что вы собираетесь изменить.

Такие комментарии очень ценны, и их нужно тщательно со%

ставлять. Они должны быть:

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

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

• Полными (чтобы знать обо всех изменениях, не прибегая

к сравнению версий вручную с помощью diff)

Регистрируйте, что было изменено и по какой причине, а не

как было изменено. О том, какие изменения сделаны, можно

узнать, сравнив версии.