Coding Style. Part 2

»Стиль программирования. Часть 2«

Читать другие материалы серии статей "Стиль программирования":
Вступление, Часть 1

Пробельные символы

Правило 9
Вступительный комментарий, защита заголовков, блок #include, блок using и определения функций разделяются двумя пустыми строками. Это позволяет визуально выделить логические блоки кода.

Правило 10
В конце файла необходимо поставить символ новой строки. Это требование стандарта C++, игнорируемое многими компиляторами.

Комментарии

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

Правило 12
Все файлы должны включать информацию о копирайте.

Правило 13
Все комментарии пишутся на английском языке (естественно, данного правила не придерживаются, как и многих других - прим. перев.).

Правило 14
Пишите комментарии для каждого класса, каждой его функции и определенных типов данных (enum/typedef/struct). Стандартное комментирование позволяет автоматически генерировать справочную документацию по исходному коду. Это может быть использовано для поддержки документации в актуальном состоянии.

Правило 15
Используйте "//" для комментариев.

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

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

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

Если символы // используются в основном для написания непосредственно комментариев, то комбинация /* */ может пригодиться в случае, когда необходимо исключить цельную часть кода из процесса разработки или отладки. C++ не поддерживает вложенные комментарии вида /* */, поэтому лучше всего воспользоваться условными директивами препроцессора (#ifdef 0 ... #endif) для разграничения большого куска кода.

Продолжение следует...
Чтобы быть в курсе последних статей, подпишись на RSS. Это просто!

Сергей Парфенюк