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

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

СТИЛЬ ПРОГРАММИРОВАHИЯ

Основной принцип хорошего стиля программирования – писать так, чтобы программу могли прочесть не только машины, но и люди.

Стиль – набор приемов или методов программирования, используемых для получения правильных, удобных для применения, легкочитаемых и, желательно, эффективных программ. Особый стиль – это программы, понятные лишь автору. Практически стиль – это набор рекомендаций по написанию программ, удовлетворяющих перечисленным выше принципам. Приведенные ниже рекомендации в равной степени подходят и к языку C, и к языку Basic.

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

Размещение инструкций. Следует записывать 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){

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

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

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

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

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

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

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

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

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

Пример.

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

/* WHEN_WHOLE_BASE */

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

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

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

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

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

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

Пример.

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

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

Дата добавления: 2014-12-27