Комментарии, идентификаторы, оформление программ

Комментарии. Одним из приемов правильного программирования является включение комментариев в программу. Комментарии не должны перефразировать программу, а должны давать дополнительную информацию, поясняющую смысл действий, выполняемых операторами.

Комментарии располагаются так, чтобы программа выглядела более наглядно.

Комментарии бывают вводными, блоковыми и операторными.

Вводные комментарии располагаются перед текстом программы, функции, процедуры. Полные вводные комментарии включают в себя:

– назначение программы;

– указание по вызову программы и ее использования;

– список и назначение основных переменных и массивов;

– указания по обмену с внешними устройствами и файлами;

– список используемых процедур и функций;

– наименование применяемых математических методов, ссылки на литературные источники, в которых содержится их описание;

– сведения о времени выполнения программы;

– специальные указания операторам;

– требуемый объем памяти;

– сведения об авторах, дата написания или последней версии программы.

Блоковые комментарии сопровождают отдельные модули и блоки программы.

Операторный комментарий описывает назначение отдельного оператора (комментарий с минимальной информацией).

Идентификаторы.Идентификаторы формируются по следующим правилам:

– осмысленность (имя напоминает соответствующую переменную в исходной программе);

– включение максимальной информации о данном объекте;

– исключение в аббревиатуре гласных из слова;

– использование префиксов или постфиксов.

Имена выбираются осмысленно так, чтобы они отражали постановку задачи. Существует так называемая «венгерская нотация» выбора идентификаторов: при выборе имен используются префиксы (предлоги). Префикс характеризует тип переменной.

«c» - тип char;

«h» - тип shortint;

«i» - тип integer;

«x», «y» - обозначение координат;

«b» - тип Boolean;

«w» - тип word;

«l» - тип longint;

«dw» - тип double word;

«fn» - function;

«s» - тип string;

«sz» - тип string, заканчивающийся символом конца строки «\0»;

«p» - тип указателя.

Следует избегать выбора подобных по написанию имен: AXIO (только буквы) и АХ10(буквы и цифры).

Если сокращают длину идентификатора, то пользуются принятыми стандартами на сокращение: каждое слово в имени подлежит сокращению, если общее количество слов более трех; в аббревиатуру всегда должны включаться начальные буквы слов (от 6 до 10); согласные важнее гласных; начало слова важнее его конца.

Оформление программ. Пропуск строк используют для выделения логически связанных блоков программы.

Для удобства и легкости чтения программы применяют отступы. Принято использовать не более 2-3 уровней вложенности, шаг отступа полагать равным 3-5 позициям. Последний уровень не должен выходить за рамки экрана.

В арифметических выражениях перенос выполняется после знака операции, в списках - после разделителя.

Пробелы служат для выделения всех конструкций программы (ключевых слов, идентификаторов, отдельных операторов и т.д.).

В одной строке обычно располагается 1 оператор.

Принято упорядочивать списки: последовательность элементов должна иметь определенную логику.

Правильно оформленная программа должна быть составлена с учетом следующих нормативов:

размер модуля 10-60 непустых строк,

размер имен 1-10 символов,

комментарии 15-25 % от размеров модуля,

длина строки 15-25 символов,

пробелы в строке 4-10.

Пример комментирования функции:

{ Вычисление тестовой функции F=x*x*x/(1+x+x*x). }

{ Параметры: x - аргумент функции. }

{ Возвращаемые значения: F - вычисленная функция. }

{ Используемые процедуры и функции: нет. }

{ Пример расчета функции в точке 0.1: Fx01:=F(0.1); }

{ Автор: Иванов А.С., 12.09.09 г. }

Function F(x: Real): Real;

begin

F := sqr(x)*x/(1+x+sqr(x));

end;