Продуманное использование комментариев и согласованное использование отступов может сделать чтение и понимание программы намного более приятным. Существует несколько различных стилей согласованного использования отступов. Автор не видит никаких серьезных оснований предпочесть один другому (хотя как и у большинства, у меня есть свои предпочтения). Сказанное относится также и к стилю комментариев.
Неправильное использование комментариев может серьезно повлиять на удобочитаемость программы, Компилятор не понимает содержание комментария, поэтому он никаким способом не может убедиться в том, что комментарий
осмыслен;
описывает программу; и
не устарел.
Непонятные, двусмысленные и просто неправильные комментарии содержатся в большинстве программ. Плохой комментарий может быть хуже, чем никакой.
Если что-то можно сформулировать средствами самого языка, следует это сделать, а не просто отметить в комментарии. Данное замечание относится к комментариям вроде:
// переменная "v" должна быть инициализирована.
// переменная "v" должна использоваться только функцией "f()".
// вызвать функцию init() перед вызовом
// любой другой функции в этом файле.
// вызовите функцию очистки "cleanup()" в конце вашей программы.
// не используйте функцию "wierd()".
// функция "f()" получает два параметра.
При правильном использовании C++ подобные комментарии как правило становятся ненужными. Чтобы предыдущие комментарии стали излишними, можно, например, использовать правила компоновки (см. этот раздел ) и видимость, инициализацию и правила очистки для классов (см. этот пункт).
Если что-то было ясно сформулировано на языке, второй раз упоминать это в комментарии не следует.
Например:
a = b+c; // a становится b+c
count++; // увеличить счетчик
Такие комментарии хуже чем просто излишни, они увеличивают объем текса, который надо прочитать, они часто затуманивают структуру программы, и они могут быть неправильными.
Автор предпочитает:
Комментарий для каждого исходного файла, сообщающий, для чего в целом предназначены находящиеся в нем комментарии, дающий ссылки на справочники и руководства, общие рекомендации по использованию и т.д.;
Комментарий для каждой нетривиальной функции, в котором сформулировано ее назначение, используемый алгоритм (если он неочевиден) и, быть может, что-то о принимаемых в ней предположениях относительно среды выполнения;
Небольшое число комментариев в тех местах, где программа неочевидна и/или непереносима; и
Очень мало что еще.
Например:
// tbl.c: Реализация таблицы имен
/*
Гауссовское исключение с частичным
См. Ralston: "A first course ..." стр. 411.
*/
// swap() предполагает размещение стека AT&T sB20.
/**************************************
Copyright (c) 1984 AT&T, Inc.
All rights reserved
****************************************/
Удачно подобранные и хорошо написанные комментарии - существенная часть программы. Написание хороших комментариев может быть столь же сложным, сколь и написание самой программы.
Заметьте также, что если в функции используются исключительно комментарии //, то любую часть этой функции можно закомментировать с помощью комментариев /* */, и наоборот.
8 8 8
| |
*
Обратная связь