Требования
к оформлению программ на языке Turbo Pascal

© М.Л. Цымблер (mzym@susu.ru)


Содержание

1. Соглашения по идентификаторам

1.1 Подбор идентификаторов
1.2 Написание идентификаторов

2. Соглашения по самодокументируемости программ

2.1 Комментарии
2.2 Спецификация подпрограммы
2.3 Спецификация программного файла или модуля

3. Соглашения по читаемости программ

3.1 Лесенка
3.2 Длина строк программного текста
3.3 Прочие рекомендации


1. Соглашения по идентификаторам

1.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.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 Комментарии

2.1.1 Комментарии в теле программы следует писать на русском языке и по существу так, чтобы программист, не участвовавший в разработке программы (но имеющий опыт работы на языке Turbo Pascal), мог без особого труда разобраться в логике программы, и, при необходимости, сопровождать данный программный продукт.

2.1.2 Рекомендуется комментарии программы писать внутри символов { и }, а (* и *) использовать при отладке программы как "заглушки" участков программного кода.

2.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. Соглашения по читаемости программ

3.1 Лесенка

"Лесенка" должна отражать структурную вложенность языковых конструкций. Рекомендуется отступ не менее  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 Прочие рекомендации

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}