9.1. Формирование листинга

Исторически листингом называли распечатку текста программы. Сейчас под этим можно понимать размещение текста программы на любом носителе.

Размещение инструкций. Следует записывать 1 инструкцию (кроме сложных) в строку.

Причины:

- соответствует правилам структурного программирования, требующим сдвигать инструкцию по строке в соответствии с уровнем ее вложенности;

- облегчает коррекцию текста.

Перенос:

- если слово не входит в строку, начинайте его с новой;

- делайте перенос после знака операции; это даст ошибку при трансляции в случае случайного удаления строки продолжения.

Пример.

a=b-c Hехорошо! a=b-c- Хорошо!

-(d+2); (d+2);

Отступы. Отступ – это абзац, выявление структуры программы. Используется, как правило, при записи сложных инструкций, имеющих в своем составе другие инструкции. Рекомедуемый размер отступа для вложенных инструкций 3-5 позиций. Размер отступа должен быть одинаков по всей программе.

Циклы.

for(i=0; i<16; i++){ For i=0 To 15

c=0; c=0

for(k=0; k<12; k++){ For k=0 To 11

c+=b[k]; d[k]=sqrt(k+1); c+=b(k) : a(k)=Sqrt(k+1)

} Next k

a[ i ]=c; a(i)=c

} Next i

Условные инструкции.

if(a>b){ If a>b Then

a=-a; b*=a; a=-a: b*=a

}else{ Else

a*=b; b=-b; a=a*b: b=-b

} End If

При переносе инструкции строки продолжения следует сдвигать вправо на 5-6 позиций.

Пропуск строк и пробелы. Пропуск строки – это вертикальная разрядка текста.

Применение:

- выделение логических частей текста;

- после нарушения естественного порядка выполнения программы (инструкции continue, break, goto, различные формы инструкции Exit);

- выделение комментариев.

Пробелы следует употреблять везде, где это улучшает читабельность.

Пример.

if(a<b && b<c){

9.2. Комментарии

Цель – пояснить логику, облегчить отладку, тестирование и сопровождение программ.

При написании комментариев следует учитывать уровень возможных читателей текста программы. Второй момент: когда писать? Рекомендуется записывать комментарии одновременно с текстом программы. После написания текста процедуры необходимо прочесть его и во всех местах, где возможен вопрос, прокомментировать.

Вопрос о количестве (объеме) комментариев является дискуссионным. Их количество зависит от сложности логики программы, числа процедур и используемых библиотечных функций, а также от того, является ли программа коллективной разработкой или нет. Можно указать такой косвенный критерий достаточности объема комментирования: объем комментариев должен быть таков, чтобы при чтении ее текста, скажем, через 1 год, можно было достаточно легко разобраться в логике и структуре программы.

Можно также привести грубый количественный критерий: ориентировочный объем комментариев – 30-50% от объема кода программы.

Различают следующие типы комментариев: оглавления, вводные, пояснительные.

Оглавления. Разумно составлять для программ, объем кода которых превышает 300 – 500 КБ.

Вводные. Записываются перед началом текста процедуры. Содержание:

- функция, выполняемая процедурой;

- характеристики и особенности процедуры.

Пример.

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

/* WHEN_WHOLE_BASE */

/* Редактировать поле, если БД не разделена */

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

Пояснительные. Служат для пояснения:

- параметров и переменных при объявлении (помещаются справа от имени);

- смысла неочевидных проверок (справа от условия);

- логического фрагмента процедуры (на отдельных строках перед началом фрагмента).

Пример.

if(adpec == NULL){ // Hесогласованная ссылка

Принцип комментирования: программа должна быть понятна без привлечения дополнительной документации.