хитрая детализация

АНТОН ПАЛАГИН AKA TONY

Спецвыпуск: Хакер, номер #071, стр. 071-038-1

(TONY@EYKONTECH.COM)

ПРАВИЛА СОСТАВЛЕНИЯ КОММЕНТАРИЕВ

КОММЕНТАРИИ — МЕРА КАЧЕСТВА ПРОГРАММНОГО КОДА. С ИХ ПОМОЩЬЮ УМЕНЬШАЕТСЯ СТОИМОСТЬ ВЛАДЕНИЯ КОДОМ

Существует два вида комментариев. Первые используются для процедуры автоматизированного документирования исходного кода и применяются в основном при разработке программных интерфейсов. Эти комментарии оформляются с помощью специальных форматов: doxygen, javadoc (без мелкософта тут, сам понимаешь, дело не обошлось, и у них тоже имеется собственный формат комментариев с трехэтажным названием XML Documentation Comments). Второй вид — это комментарии, сопровождающие исходный код, объясняющие его работу, описывающие данные и раскрывающие непонятные и сомнительные моменты.

[автоматизированное документирование]

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

[комментарии исходного кода.]

В отличие от комментариев для автоматизированного документирования, эти комментарии используются в любом программном коде. Стоимость владения исходным кодом уменьшается прямо пропорционально количеству и качеству комментариев. Это связано с тем, что хорошо структурированный и комментированный код легче поддерживается и сопровождается. То есть программистам просто требуется меньше времени для того, чтобы разобраться с ним. Для анализа качества исходного кода можно использовать специализированные инструменты (например, together), которые подсчитывают различные метрики кода, описывающие его качество.

[используй одну нотацию имен.]

Существует достаточно большое количество нотаций имен программных сущностей, а также стилей кодирования. Выбери себе одну из таких нотаций и стиль кодирования, и следуй им. Если ты работаешь в команде, то вся команда также должна придерживаться единого стиля.

[будь внимательней при выборе кодировки и языка.]

В последнее время ситуация с поддержкой кириллицы в средах разработки стала заметно лучше, однако на встраиваемых платформах до сих пор наблюдаются проблемы с русским языком. И твой файл с комментариями в кодировке CP-1251, написанными в MSVC, ни за что не откроется в том же Eclipse под QNX. Так что не исключено, что придется писать комментарии на английском языке.

[форматируй и структурируй код.]

Обращай внимание на форматирование своего кода и его структуру. Выравнивай фигурные скобки по одной колонке и строки по отступам. Обязательно делай так, чтобы внутри фигурных скобок код был выровнен по левому краю и с отступом от скобок. Используй для этого табуляцию. Объединяй несколько строк кода в группы по 3-5 строчек, которые выполняют однородное по своему смыслу действие. Группы отделяй друг от друга пустыми строками.