Требования
к оформлению программ на языке Turbo
Pascal
© М.Л. Цымблер (mzym@susu.ru)
Содержание
1. Соглашения по идентификаторам
2. Соглашения по самодокументируемости программ
2.1 Комментарии
2.2 Спецификация подпрограммы
2.3 Спецификация программного файла или модуля
3. Соглашения по читаемости программ
3.1 Лесенка
3.2 Длина строк программного текста
3.3 Прочие рекомендации
1. Соглашения по идентификаторам
1.1.1 Все идентификаторы должны выбираться из соображений читаемости и максимальной семантической нагрузки. Например:
const Eps = 0.0001; { точность } var Sum : Integer;{ сумма } Message: String; { сообщение }
Неудачными можно считать идентификаторы:
const UU = 0.0001; { точность } var Kk : Integer;{ сумма } Zz : String; { сообщение }
1.1.2. Идентификаторы рекомендуется подбирать из слов английского языка. Например:
1) procedure Beep(Hertz, MSec: Word); { выдает звуковой сигнал заданной частоты и длительности }
2) function ExistFile(FName: String): Boolean; { выдает True, если файл с именем FName существует }
3) var Done: Boolean; { признак окончания работы с программой } Width, Height: Real; { размеры изделия (ширина, высота) }
Не очень удачными можно считать идентификаторы:
1) procedure Zvuk(Chast, Dlit: Word); { выдает звуковой сигнал заданной частоты и длительности }
2) function EstFile(Im: String): Boolean; { выдает True, если файл с именем Im существует }
3) var Konec: Boolean; { признак окончания работы с программой } Shirina, Vysota: Real; { размеры изделия (ширина, высота) }
1.2.1 Зарезервированные слова языка Turbo Pascal писать только маленькими буквами. Например:
type, var, const; procedure, function; begin, end; if, then, else; repeat, until; case; while; and, not, or; unit, uses, interface, implementation.
1.2.2 В любых идентификаторах каждое слово, входящее в идентификатор, писать, начиная с большой буквы, остальные буквы -- маленькие. В этом смысле символ подчеркивания "_" между словами идентификатора можно считать излишним. Например:
1) var NextX, LastX: Real; { следующая и предыдущая итерация } BeepOnError: Boolean; { подавать ли звуковой сигнал при неправильном вводе пользователя? }
2) function GraphErrorMsg(ErrCode: Word): String; { стандартная функция модуля Graph; выдает описание ошибки использования графики по ее коду }
3) begin Write('Введите целое число, большее 10 ==>_ '); ReadLn(Num); if Num > 10 then WriteLn('OK'); end.
4) var FileName: String;{ а не File_Name } type ByteArray = array 0..65534] of Byte; { а не Array_Of_Byte }
1.2.3 Рекомендуется идентификаторы, состоящие из одной буквы, писать большой буквой, если они не являются счетчиками циклов. Например:
1) A := A + B; B := A - B; A := A - B;
2) procedure DeleteNode(var L: List; I: Word); { удалить звено c номером I из списка L }
3) for i := 1 to N do for j := 1 to N do Ai, j] := (i + j) / 2;
2. Соглашения по самодокументируемости программ
2.1.1 Комментарии в теле программы следует писать на русском языке и по существу так, чтобы программист, не участвовавший в разработке программы (но имеющий опыт работы на языке Turbo Pascal), мог без особого труда разобраться в логике программы, и, при необходимости, сопровождать данный программный продукт.
2.1.2 Рекомендуется комментарии программы писать внутри символов { и }, а (* и *) использовать при отладке программы как "заглушки" участков программного кода.
Для каждой пользовательской подпрограммы (процедуры или функции) должна быть
описана в виде комментария
спецификация, содержащая следующую информацию:
а) назначение подпрограммы;
б) описание семантики параметров-значений (параметров, передаваемых по значению),
если она неочевидна;
в) описание семантики параметров-переменных (параметров, передаваемых по ссылке),
если она неочевидна.
г) для функции: описание семантики возвращаемого значения, если она неочевидна.
Например:
1) семантика параметров и возвращаемого значения очевидна function IsLeapYear(Y: Word): Boolean; { возвращает True, если год Y -- високосный }
2) семантика параметров очевидна, семантика возвращаемого значения неочевидна function DayOfWeek(D, M, Y: Word): Byte; { Возвращает день недели даты D/M/Y; год Y должен быть в отрезке 1582..4902; результат: ВСК = 0, ПНД = 1, ВТР = 2, ... СБТ = 6 }
3) семантика параметров и возвращаемого значения неочевидна const MaxN = 10; type Matrix = array 1..MaxN, 1..MaxN] of Real; Vector = array 1..MaxN] of Real; procedure Gauss(A: Matrix; B: Vector; Eps: Real; var X: Vector; var HasSolution: Boolean; var NumOfRoots: Integer; var Det: Real; var AForReverse: Matrix; var BForReverse: Vector); { Решение системы линейных алгебраических уравнений методом Гаусса. Входные данные: A -- матрица коэффициентов системы; B -- столбец свободных членов системы; Eps -- точность вычислений. Выходные данные: X -- вектор решения; HasSolution -- флаг, устанавливаемый в True, если решение системы существует, и в False во всех остальных случаях; NumOfRoots -- число корней в решении системы, может принимать значения: 0 -- если решение системы не существует, MaxN -- если решение системы существует и единственно, MaxInt -- если существует бесконечное множество решений; Det -- значение определителя матрицы A; AForReverse -- нижняя треугольная матрица, полученная из A в в результате выполнения прямого хода алгоритма Гаусса; BForReverse -- столбец свободных членов, полученный из B в в результате выполнения прямого хода алгоритма Гаусса. }
Замечание:
Если процедура (функция) реализует какой-либо вычислительный метод (например:
нахождение площади
фигуры методом трапеций, поиск минимума функции методом Ньютона и т.п.), рекомендуется
в теле процедуры (функции) поместить комментарий с кратким описанием метода, либо ссылку
на источник, где описан метод.
2.3 Спецификация программного файла или модуля
Программный файл или модуль (unit) должен начинаться со спецификации
в виде комментария, содержащего
следующую информацию:
а) идентификация (имя) файла;
б) фамилия и копирайт автора;
в) дата написания файла;
г) версия языка программирования и замечания по компиляции
программы (модуля) в других версиях языка
(если требуется);
д) назначение программы (модуля);
Например:
1) { PRIMES.PAS -------------------------- (c)оздал: Иванов И.И. дата : 01/09/93 для : Turbo Pascal 6.0 ------------------------------------------------------- Подсчет количества простых чисел в промежутке 1..200]. }
2) { MYMENU.PAS -------------------------- (c)оздал: Иванов И.И. дата : 01/09/93 для : Turbo Pascal 6.0 ------------------------------------------------------- Модуль экспортирует процедуры и функции, поддерживающие горизонтальные и вертикальные меню. }
Замечание:
В программном файле после заголовка Program <имя
программы>; (в файле с пользовательским
модулем -- после заголовка unit <имя модуля>;) рекомендуется поместить
комментарий с указаниями
по запуску программы и работе с ней (указаниями по использованию модуля другими
программистами) или
ссылку на источник, который использован при составлении программы (модуля).
3. Соглашения по читаемости программ
"Лесенка" должна отражать структурную вложенность языковых конструкций. Рекомендуется отступ не менее 2-х и не более 8-и пробелов. Принятого отступа нужно придерживаться во всем тексте программы. Правила написания конструкции begin ... end и других:
а1) if <условие> then begin <операторы> end;
а2) if <условие> then <оператор>;
а3) if <условие> then begin <операторы> end else begin <операторы> end;
б1) while <условие> do begin <операторы> end;
б2) while <условие> do <оператор>;
в1) for <счетчик> := <начальное значение> to <конечное значение> do begin <операторы> end;
в2) for <счетчик> := <нач/знач> to <кон/знач> do <оператор>;
г1) case <выражение> of <выражение>: <оператор>; ....... end;
г2) case <выражение> of <выражение>: <оператор>; ....... else <оператор>; end;
г3) case <выражение> of <выражение>: begin <операторы> end; ....... end;
Например:
1) function Sign(X: Real): Integer; { выдает знак числа X } begin if X > 0 then Sign := 1 else if X < 0 then Sign := -1 else Sign := 0; end;
2) procedure Equation(A, B, C: Real; var X1, X2: Real; var Num: Byte); { нахождение действительных корней квадратного уравнения; A, B, C -- коэффициенты X1, X2 -- корни (если действительного решения нет, то полагаются равными 0); Num -- число корней (0, 1, или 2) } var D: Real; begin D := Sqr(B) - 4 * A * C; if D < 0 then begin Num := 0; X1 := 0; X2 := 0; end else begin X1 := (- B + Sqrt(D)) / (2 * A); X2 := (- B - Sqrt(D)) / (2 * A); if X1 = X2 then Num := 1 else Num := 2; end; end;
3.2 Длина строк программного текста
Длина строк программы не должна превышать ширины экрана (80 символов).
3.3.1 Рекомендуется операнды бинарных операций (+, := и т.п.) отделять от знака операции одним пробелом " ". Например:
Sum := A + B;
3.3.2 Рекомендуется при перечислении идентификаторов после запятой "," ставить один пробел " ". Например:
1) WriteLn('Сумма: ', A + B, ';', 'Разность: ', A - B, '.');
2) var Day, Month, Year: Word; i, j, k, l, m, n: Integer;
3.3.3 Рекомендуется всегда писать символ-разделитель операторов ";" (непосредственно после оператора). Например:
1) case Num of 1: WriteLn('один...'); 2: WriteLn('два...'); 3: WriteLn('три...'); { <-- здесь } else WriteLn('много!'); { <-- и здесь } end;
2) if N < 0 then begin WriteLn('Введено неверное значение N, прерываем работу!'); Halt; { <-- здесь } end;
3.3.4 Рекомендуется после символа-спецификатора типа ":"
ставить один пробел " ".
Например:
1) var i, j, k: Integer;
2) function SizeOfFile(FName : String) : LongInt; { выдает размер файла с именем FName в байтах; если файл не найден, возвращает -1 }
3.3.5 Рекомендуется 16-ричные числа писать большими буквами. Например:
1) const BadDate = $FFFF; kbEnter = $1D; { код клавиши <Enter> }
3.3.6 Рекомендуется директивы компилятора писать большими буквами, а условные определения -- так же, как идентификаторы (см. 1. Соглашения по идентификаторам). Например:
1) type {$IFOPT N+} RealType = Extended; {$ELSE} RealType = Real; {$END}
2) {$DEFINE Protect} .... {$IFDEF Protect} WriteLn('Программа защищена от копирования!'); {$ENDIF}