Комментирование кода в C++

Все языки программирования стремятся облегчить нашу с Вами работу, предлагая все новые и новые способы, позволяющее не делать ничего по нескольку раз. Именно так появились объектно-ориентированные языки программирования, которые позволяли использовать код дважды. Однако сегодня мы поговрим не об этом. Наша сегодняшняя тема - комментирование кода в C и C++. Благодаря комментариям Вам не нужно несколько раз переосмысливать код, написанный вчера, или много месяцев назад. Сначала разберемся со стилями расстановки коментариев.

Блочный комментарий.

Этот тип - настоящая головная боль при поддержке, потому как обязует программиста к расстановке и левых и правых разделителей (чаще всего это звездочки).

Например так:

/***********************************
*                                  *
* Данный исходник разработан       *
* Мяутом в 2004-м году.            *
*                                  *
************************************/

Пусть у меня появился соавтор:

/***********************************
*                                  *
* Данный исходник разработан       *
* Мяутом, Вторым и третьим программистом в 2005-м году.            *
*                                  *
************************************/

Теперь надо перерасставлять все разделители.

Вы наверное возразите: "Можно же опускать звездочки справа". Это конечноже решает проблему, но все-таки Вам в любом случае придется продлевать первую и последнюю строку.

/***********************************
*
* Данный исходник разработан
* Мяутом в 2004-м году.
*
************************************/

Миримизированый блочный комментарий.

Можно вообще обойтись без звездочек:

/*

  Данный исходник разработан
  Мяутом в 2004-м году.
 
                                   */

Есть и другие типы, но они встречаются реже.

/*
*
* Данный исходник разработан
* Мяутом в 2004-м году.
*
*/

В стандарте C99 и в C++ описан еще один тип комметариев: //. Он действует в пределах от самой последовательности двух слэшей до следующего перевода строки.

Если в конце строки стоит символ '\', считается комментарием и следующая строка.

Теперь поговорим о самом комментирование кода. Безусловно, оно очень важно при написании программы, особенно если программистов несколько.

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

 i++; //Прибавление 1 к i

Иногда даже встречаются необычные образцы:

 int var3947l; //Не помню

И не забывайте, что помимо комметариев, хорошие идентификаторы также делают код читабельнее.

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

 CurrentFont->Name = Current->Data->Font.Face; //Выбор текущего шрифта
 CurrentFont->Color = Current->Data->Font.Color; //Выбор цвета шрифта
 CurrentFont->Size = Current->Data->Font.Size; //Выбор размера шрифта
 Canvas->Font->Assign(CurrentFont); //Установка шрифта

и

//Установка и настройка текущего шрифта
 CurrentFont->Name = Current->Data->Font.Face;
 CurrentFont->Color = Current->Data->Font.Color;
 CurrentFont->Size = Current->Data->Font.Size;
 Canvas->Font->Assign(CurrentFont);

В-третьих, не всегда пользуйтесь вторым правилом :) Вот вам пример:

 if(PolygonList[i].maxz==0) glTexCoord3f(Point->x/PolygonList[i].maxx, 1., Point->y/PolygonList[i].maxy);
 else if(PolygonList[i].maxy==0) glTexCoord3f(Point->x/PolygonList[i].maxx, 1., Point->z/PolygonList[i].maxz);
 else if(PolygonList[i].maxx==0) glTexCoord3f(1., Point->y/PolygonList[i].maxy, Point->z/PolygonList[i].maxz);
 else glTexCoord3f(Point->x/PolygonList[i].maxx, Point->y/PolygonList[i].maxy, Point->z/PolygonList[i].maxz);

Этот кусок я не стал по-началу комментровать, а зря. Дело в том, что модели не всегда имеют целые значения вершин, и как следствие, могут не правильно текстурироваться. С помощью этого кода и приводил их значения к целым. Через несколько дней я вернулся к этому коду. И что вы думаете я написал?

 glTexCoord3f(Point->x, Point->y, Point->z);

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

В-четвертых, комментируйте закрывающие скобки. Это поможет вспомнить Вам, какая из скобок к какому блочному оператору строк.

Некоторые программмисты предлагают еще пятое правило - не комментируйте сам код, а используйте дерективы препроцессора. Я сам его не соблюдаю, потому и Вам морочить голову не буду.

//(с) Статью подготовил Кляус Сергей.