Бьерн Страуструп.
Язык программирования С++
94
учебниках по языкам программирования, подобных этой книге. Это одна из многих причин, по которой
учебная программа отличается от настоящей.
Можно рекомендовать такой стиль введения комментариев в программу:
[1] начинать с комментария каждый файл программы: указать в общих чертах, что в ней
определяется, дать ссылки на справочные руководства, общие идеи по сопровождению
программы и т.д.;
[2] снабжать комментарием каждое определение класса или шаблона типа;
[3] комментировать каждую нетривиальную функцию, указав: ее назначение, используемый
алгоритм (если только он неочевиден) и, возможно, предположения об окружении, в котором
работает функция;
[4] комментировать определение каждой глобальной переменной;
[5] давать некоторое число комментариев в тех местах, где алгоритм неочевиден или
непереносим;
[6] больше практически ничего.
Приведем пример:
// tbl.c: Реализация таблицы имен.
/*
Использован метод Гаусса
см. Ральстон "Начальный курс по ..." стр. 411.
*/
// в swap() предполагается, что стек AT&T начинается с 3B20.
/************************************
Авторские права (c) 1991 AT&T, Inc
Все права сохранены
**************************************/
Правильно подобранные и хорошо составленные комментарии играют в программе важную роль.
Написать хорошие комментарии не менее трудно, чем саму программу, и это - искусство, в котором
стоит совершенствоваться.
Заметим, что если в функции используются только комментарии вида //, то любую ее часть можно
сделать комментарием с помощью /* */, и наоборот.
Достарыңызбен бөлісу: