Комментарии и Выравнивание

<!--StartFragment -->

Продуманное использование комментариев и согласованное использование отступов может сделать чтение и понимание программы намного более приятным. Существует несколько различных стилей согласованного использования отступов. Автор не видит никаких серьезных оснований предпочесть один другому (хотя как и у большинства, у меня есть свои предпочтения). Сказанное относится также и к стилю комментариев.

Неправильное использование комментариев может серьезно повлиять на удобочитаемость программы, Компилятор не понимает содержание комментария, поэтому он никаким способом не может убедиться в том, что комментарий


  • осмыслен;

  • описывает программу; и

  • не устарел.


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

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

// переменная \"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
****************************************/


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

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



Опубликовал admin
23 Мар, Вторник 2004г.



Программирование для чайников.