Правила программирования на Си и Си++



         

27. Комментарий должен предоставлять только нужную для сопровождения информацию - часть 3


47 ** Все права сохраняются.                               **

48 **                                                      **

49 ** Никакая часть этой подпрограммы не может быть        **

50 ** воспроизведена в любой форме без явного разрешения   **

51 ** в трех экземплярах со стороны отдела Министерства    **

52 ** сокращения персонала. Нарушители будут лишены своего **

53 ** старшего сына.                                       **

54 **------------------------------------------------------**

55 */

56 inline equal (

char *s1, char *s2 )

57 {

58     return !strcmp( s1, s2 ); // Возвращает истину, если

59 }                             // строки равны.

Действительная проблема заключается в том, что этот тип заголовков нарушает ряд других правил, таких как: "не комментируй очевидное", "исключай неразбериху" и так далее. Тот минимум реальной информации, который содержится в этом заголовке, относится к системе регистрации изменений, а не к исходному тексту программы. Комментарии в программе должны сообщать вам сведения, полезные при сопровождении.

28. Комментарии должны быть в блоках

Комментарии в общем воспринимаются лучше, когда помещаются в многострочных блоках, которые чередуются с блоками текста программы. Для этого комментарий должен описывать на высоком уровне, что делают несколько последующих строк кода. Если комментарии попадаются через строчку, то это похоже на чтение двух книг одновременно, причем по строке из каждой по очереди. И если программа, комментируемая вами, сложная, то вы можете воспользоваться сносками:

// Вот блочный комментарий, описывающий последующий блок

// программы. После общего резюме я описываю некоторые

// особенности:

//

// 1. Этот комментарий описывает, что происходит в строке

// с меткой 1

//

// 2. Этот комментарий описывает, что происходит в строке

// с меткой 2

//

// В точке 1 алгоритм устанавливается на ...

//

here_is_the_code();

while( some_condition )

{

  this_code_is_rather_obscure();      /* 1 */

}

more_stuff_here();

while( some_condition )

{

  this_code_is_also_obscure();        /* 2 */

}




Содержание  Назад  Вперед