3.4 Комментарии и расположение текста.

• Глава 3. Выражения и операторы
  • 3.4 Комментарии и расположение текста

Программу гораздо легче читать, и она становится намного понятнее, если разумно использовать комментарии и систематически выделять текст программы пробелами. Есть несколько способов расположения текста программы, но нет причин считать, что один из них - наилучший. Хотя у каждого свой вкус. То же можно сказать и о комментариях.

Однако можно заполнить программу такими комментариями, что читать и понимать ее будет только труднее. Транслятор не в силах понять комментарий, поэтому он не может убедиться в том, что комментарий:

[1] осмысленный,

[2] действительно описывает программу,

[3] не устарел.

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

Если некий факт можно прямо выразить в языке, то так и следует делать, и не надо считать, что достаточно упомянуть его в комментарии. Последнее замечание относится к комментариям, подобным приведенным ниже:

           // переменную "v" необходимо инициализировать.

           // переменная "v" может использоваться только в функции "f()".

           // до вызова любой функции из этого файла
           // необходимо вызвать функцию "init()".

           // в конце своей программы вызовите функцию "cleanup()".

           // не используйте функцию "weird()".

           // функция "f()" имеет два параметра.

При правильном программировании на С++ такие комментарии обычно оказываются излишними. Чтобы именно эти комментарии стали ненужными, можно воспользоваться правилами связывания ($$4.2) и областей видимости, а также правилами инициализации и уничтожения объектов класса ($$5.5).
Если некоторое утверждение выражается самой программой, не нужно повторять его в комментарии. Например:

           a = b + c;      // a  принимает значение b+c
           count++;        // увеличим счетчик count

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

Можно рекомендовать такой стиль введения комментариев в программу:

• [1] начинать с комментария каждый файл программы: указать в общих чертах, что в ней определяется, дать ссылки на справочные руководства, общие идеи по сопровождению программы и т.д.;
• [2] снабжать комментарием каждое определение класса или шаблона типа;
• [3] комментировать каждую нетривиальную функцию, указав: ее назначение, используемый алгоритм (если только он неочевиден) и, возможно, предположения об окружении, в котором работает функция;
• [4] комментировать определение каждой глобальной переменной;
• [5] давать некоторое число комментариев в тех местах, где алгоритм неочевиден или непереносим;
• [6] больше практически ничего.

Приведем пример:

           //  tbl.c: Реализация таблицы имен.

           /*
                 Использован метод Гаусса
                 см. Ральстон "Начальный курс по ..." стр. 411.
           */

           // в swap() предполагается, что стек AT&T начинается с 3B20.

           /************************************

             Авторские права (c) 1991 AT&T, Inc
             Все права сохранены

           **************************************/

Правильно подобранные и хорошо составленные комментарии играют в программе важную роль. Написать хорошие комментарии не менее трудно, чем саму программу, и это - искусство, в котором стоит совершенствоваться.

Заметим, что если в функции используются только комментарии вида //, то любую ее часть можно сделать комментарием с помощью /* */, и наоборот.