|
Страница 48 из 68
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
Все права сохранены
**************************************/
Правильно подобранные и хорошо составленные комментарии играют в
программе важную роль. Написать хорошие комментарии не менее
трудно, чем саму программу, и это - искусство, в котором стоит
совершенствоваться.
Заметим, что если в функции используются только комментарии
вида //, то любую ее часть можно сделать комментарием с помощью
/* */, и наоборот. |