[@McConnell2004]
Общие аспекты
- Может ли программист, взглянувший на код, сразу понять его?
- Объясняют ли комментарии цель кода или резюмируют ли они выполняемые в коде действия вместо того, чтобы просто повторять код?
- Используете ли вы процесс программирования с псевдокодом для сокращения времени комментирования?
- Переписали ли вы хитрый код вместо того, чтобы комментировать его?
- Актуальны ли комментарии?
- Ясны ли комментарии? Корректны ли они?
- Позволяет ли стиль комментирования с легкостью изменять комментарии?
Операторы и абзацы
- Избегаете ли вы комментариев в концах строк?
- Стремитесь ли вы отвечать в комментариях на вопрос “почему”, а не “как”?
- Готовят ли комментарии читателя к последующему коду?
- Каждый ли комментарий важен? Были ли удалены или улучшены избыточные, посторонние и неуместные комментарии?
- Документируете ли вы сюрпризы?
- Избегаете ли вы сокращений?
- Ясно ли различие между общими и детальными комментариями?
- Комментируете ли вы недокументированные возможности или код, предотвращающий ошибки языка или среды?
Объявления данных
- Указываете ли вы единицы измерения данных в местах объявления данных?
- Указываете ли вы диапазоны допустимых значений численных величин?
- Комментируете ли вы смысл закодированных значений?
- Комментируете ли вы ограничения входных данных?
- Документируете ли вы флаги до уровня отдельных битов?
- Комментируете ли вы каждую глобальную переменную в месте ее объявления?
- Поясняете ли вы при каждом использовании глобальной переменной ее глобальный характер при помощи конвенции именования, комментария или обоих способов?
- Заменили ли вы магические числа на именованные константы или переменные, вместо того чтобы ограничиться простым документированием?
Управляющие структуры
- Комментируете ли вы каждый управляющий оператор?
- Комментируете ли вы концы длинных или сложных управляющих структур или упрощаете ли вы эти структуры по мере возможности, чтобы они не требовали комментариев?
Методы
- Комментируете ли вы назначение каждого метода?
- Указываете ли вы в комментариях к методам в случае надобности другую информацию, такую как входные и выходные данные, предположения об интерфейсе, ограничения, исправленные ошибки, глобальные эффекты и источники алгоритмов?
Файлы, классы и программы
- Включает ли программа краткий документ, подобный документу Книжной парадигмы, предоставляющий общую информацию об организации программы?
- Описали ли вы назначение каждого файла?
- Указали ли вы в листинге фамилию и имя автора, адрес электронной почты и номер телефона?
Ключевые моменты
- Вопрос о том, стоит ли комментировать код, вполне обоснован. При плохом выполнении комментирование является пустой тратой времени и иногда причиняет вред. При грамотном применении комментирование полезно.
- Основная часть критически важной информации о программе должна содержаться в исходном коде. На протяжении жизни программы актуальности исходного кода уделяется больше внимания, чем актуальности любого другого ресурса, поэтому важную информацию полезно интегрировать в код.
- Хороший код сам является самой лучшей документацией. Если код настолько плох, что требует объемных комментариев, попытайтесь сначала улучшить его.
- Комментарии должны сообщать о коде что-то такое, что он не может сообщить сам — на уровне резюме или уровне цели.
- Некоторые стили комментирования заставляют выполнять много нудной канцелярской работы. Используйте стиль, который было бы легко поддерживать.