[@McConnell2004]

Общие аспекты

• Может ли программист, взглянувший на код, сразу понять его?
• Объясняют ли комментарии цель кода или резюмируют ли они выполняемые в коде действия вместо того, чтобы просто повторять код?
• Используете ли вы процесс программирования с псевдокодом для сокращения времени комментирования?
• Переписали ли вы хитрый код вместо того, чтобы комментировать его?
• Актуальны ли комментарии?
• Ясны ли комментарии? Корректны ли они?
• Позволяет ли стиль комментирования с легкостью изменять комментарии?

Операторы и абзацы

• Избегаете ли вы комментариев в концах строк?
• Стремитесь ли вы отвечать в комментариях на вопрос “почему”, а не “как”?
• Готовят ли комментарии читателя к последующему коду?
• Каждый ли комментарий важен? Были ли удалены или улучшены избыточные, посторонние и неуместные комментарии?
• Документируете ли вы сюрпризы?
• Избегаете ли вы сокращений?
• Ясно ли различие между общими и детальными комментариями?
• Комментируете ли вы недокументированные возможности или код, предотвращающий ошибки языка или среды?

Объявления данных

• Указываете ли вы единицы измерения данных в местах объявления данных?
• Указываете ли вы диапазоны допустимых значений численных величин?
• Комментируете ли вы смысл закодированных значений?
• Комментируете ли вы ограничения входных данных?
• Документируете ли вы флаги до уровня отдельных битов?
• Комментируете ли вы каждую глобальную переменную в месте ее объявления?
• Поясняете ли вы при каждом использовании глобальной переменной ее глобальный характер при помощи конвенции именования, комментария или обоих способов?
• Заменили ли вы магические числа на именованные константы или переменные, вместо того чтобы ограничиться простым документированием?

Управляющие структуры

• Комментируете ли вы каждый управляющий оператор?
• Комментируете ли вы концы длинных или сложных управляющих структур или упрощаете ли вы эти структуры по мере возможности, чтобы они не требовали комментариев?

Методы

• Комментируете ли вы назначение каждого метода?
• Указываете ли вы в комментариях к методам в случае надобности другую информацию, такую как входные и выходные данные, предположения об интерфейсе, ограничения, исправленные ошибки, глобальные эффекты и источники алгоритмов?

Файлы, классы и программы

• Включает ли программа краткий документ, подобный документу Книжной парадигмы, предоставляющий общую информацию об организации программы?
• Описали ли вы назначение каждого файла?
• Указали ли вы в листинге фамилию и имя автора, адрес электронной почты и номер телефона?

Ключевые моменты

• Вопрос о том, стоит ли комментировать код, вполне обоснован. При плохом выполнении комментирование является пустой тратой времени и иногда причиняет вред. При грамотном применении комментирование полезно.
• Основная часть критически важной информации о программе должна содержаться в исходном коде. На протяжении жизни программы актуальности исходного кода уделяется больше внимания, чем актуальности любого другого ресурса, поэтому важную информацию полезно интегрировать в код.
• Хороший код сам является самой лучшей документацией. Если код настолько плох, что требует объемных комментариев, попытайтесь сначала улучшить его.
• Комментарии должны сообщать о коде что-то такое, что он не может сообщить сам — на уровне резюме или уровне цели.
• Некоторые стили комментирования заставляют выполнять много нудной канцелярской работы. Используйте стиль, который было бы легко поддерживать.