17 ** СПЕЦИАЛЬНЫЕ ТРЕБОВАНИЯ:

18 ** нет.

19 **

2 0 ** АРГУМЕНТЫ: **

21 ** char *s1; Указатель на первую сравниваемую строку **

22 ** char *s2; Указатель на вторую сравниваемую строку ** 2 3** **

24 ** РЕЗУЛЬТАТЫ: **

25 ** Функция возвращает true, если строки-аргументы ** 2 6 ** лексикографически идентичны.

27 **

2 8 ** КОММЕНТАРИИ: **

29 ** нет. *

30 **

31 ** ПРИМЕЧАНИЯ ПО РЕАЛИЗАЦИИ:

32 ** нет. *

33 ** **

34 ** ИСТОРИЯ ИЗМЕНЕНИЙ: **

35 ** **

36 **

3 6 ** АВТОР: Эндрюс, Джозеф 37 ** ДАТА: 12, июль, 1743

по + + T/rOT\/rirUirUT/rir . и-, ТТ-, ттт ттг> у-

38 ** ИЗМЕНЕНИЕ: Начальное состояние

39 ** **

40 ** АВТОР: Джонс, Том **

41 ** ДАТА: 13, июль, 1743 **

42 ** ИЗМЕНЕНИЕ: Изменены имена аргументов со str1, str2. **

43 ** **

44 ** Вест текст программа: в этом файле охраняется **

45 ** авторским правом. * 4 6 ** Copyright (c) В1м1щленная корпорация **

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

48 ** **

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

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

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

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

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

55 */

56 inline equal ( char *s1, char *s2 )

57 {

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

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

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

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

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

Вот блочн1й комментарий, описывающий последующий блок программ!. После общего резюме я описываю некоторые особенности:

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 */

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

Выравнивайте начало и конец комментария вертикально в многострочных комментариях.

/* Первая строка,

* вторая строка,

* третья строка.

Если ваш компилятор их поддерживает, то здесь помогут комментарии в стиле Си++:

* * *

***********************************************************

Вертикальный столбец из звездочек слева облегчает зрительное разделение комментария и программы

void the function( void )

далее настоящая функция. code goes here();

Первая строка, вторая строка, третья строка.

Есть две причины появления этого правила, они обе демонстрируются в последующей программе:

/**********************************************************

void the function( void )

Это многострочный комментарий, выполняющий все, что должен делать комментарий.

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

***********************************************************

void the function( void )

далее настоящая функция. code goes here();

/**********************************************************/

Во-первых, заметили ли вы, что я забыл поместить / в конце второй строки звездочек? Таким путем можно запросто терять целые функции. Во-вторых, трудно заметить, где оканчивается комментарий и начинается текст программы. Исправьте обе ошибки следующим образом:

/***********************************************************

* void the function( void )

* Это многострочный комментарий, выполняющий все, что должен

* делать комментарий.