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

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

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

Причины:

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

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

Перенос:

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

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

Пример.

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

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

Отступы. Отступ – это абзац, выявление структуры программы. Используется, как правило, при записи сложных инструкций, имеющих в своем составе другие инструкции. Рекомедуемый размер отступа для вложенных инструкций 4-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=c+b(k) : a(k)=sqr(k+1)

} next k

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

} next i

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

if(a>b){ if a>b then

a=-a; a=-a

b*=a; b=b*a

}else{ else

a*=b; a=a*b

b=-b; b=-b

} end if

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

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

Применение:

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

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

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

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

Пример.

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

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

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

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

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

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

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

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

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

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

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

Пример.

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

/* WHEN_WHOLE_BASE */

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

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

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

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

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

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

Пример.

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

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