Границы

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

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

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

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

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

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

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

Флажки

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

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

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

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

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

Если файл исходного кода автоматически создан в процессе сборки, необходимо каким-либо образом включить в заголовок комментарий, который четко информирует (БОЛЬШИМИ ПРОПИСНЫМИ БУКВАМИ) об источнике происхождения файла. Иначе кто-нибудь по ошибке станет его редактировать, не зная, что потеряет свой труд после очередной сборки.