Глава 5. Соглашения об именах и комментариях 111

// Эта функция получает на входе строку (char *string), // представляющую собой пару имя/фамилия в виде (фамилия, имя), // преобразует ее в форму имя фамилия и возвращает результат в // переменной char *result. Обязанность обеспечить нужный объем // памяти для результата лежит на вызывающей функции.

void ConvertInternalNameToFirstLast(char *string; char *result) (

)

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

Замечание

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

Переменные

Объявление важных переменных, заслуживающих описания, или разъяснения, должно сопровождаться кратким комментарием. Желательно, чтобы эти комментарии были выдержаны в едином стиле, например, начинались с заглавной буквы и завершались точкой. Многие программисты выравнивают комментарии табуляцией:

char *p; // Итератор символов исходной строки. char *q; // Итератор символов строки результата. int numberOf Names =0; // Количество обработанных имен.

Соблюдение четкого выравнивания доставляет некоторые хлопоты, поэтому смотрите сами, что вам больше нравится:

char *p; // Итератор символов исходной строки. char *q; // Итератор символов строки результата. int numberOfNames = 0; // Количество обработанных имен.

Хорош тот стиль, который вам больше подходит.

Блоки

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