Мельница данных- Соглашения  (раздел целиком)  (13.06.2024)
Соглашения

1. Соглашения о наименованиях

В качестве вводимых (объявляемых) идентификаторов необходимо использовать так называемую нотацию InfixCaps. Если при создании имени используется несколько слов, то необходимо использовать заглавную букву для каждого слова в имени. Для разделения слов нельзя использовать символ подчеркивания. Все сущности именуются на английском языке, при этом использование сокращений является оправданным только в случае, если длина образуемого имени не согласуется с внешними по отношению к соображениям бизнес-логики ограничениям.

  • Имя класса должно начинаться с латинской буквы 'T'.
    Пример
    Имя Наименование
    TObjectList Список объектов
    TLearnPlan Учебный план
  • Имя поля должно начинаться с латинской буквы 'F'.
    Пример
    Имя Наименование
    FLearnPeriod Период обучения
    FExamMark Оценка за экзамен
  • Имя свойства не имеет префикса.
    Пример
    Имя Наименование
    ExamKind Вид рубежного испытания
    ContactPhone Контактный телефон
    Если членом класса для чтения свойства является поля, то имя свойства должно повторять имя поля без префикса 'F'. Если членом класса для чтения свойства является метод, то имя поля должно повторять имя метода без слова 'Get'.
  • Имя параметра не имеет префикса.
    Пример
    Имя Наименование
    OrderNumber Номер приказа
    ExamDate Дата проведения экзамена
    Параметры, используемые для инициализации значений полей, должны иметь имя, повторяющее имя поля без префикса 'F'. При компиляции тела метода, написанного на языке PascalScript имена параметров и имена свойств будут распознаваться в соответствии с порядком разбора идентификаторов, как это описано здесь и здесь.
  • Имена методов должны представлять собой императивный глагол на английском языке, выражающий смысл того, что метод делает. Имена методов не имеют префикса. Имена методов, используемых для получения значений свойств должны (как члены класса для чтения), должны начинаться со слова Get. Имена методов, используемых для установки значений свойств должны (как члены класса для записи), должны начинаться со слова Set.
    Пример
    Имя Наименование
    CountMarkSumm Вычислить сумму баллов
    GetAge Получить значение возраста
    SetMark Установить значение оценки
  • Имена локальных переменных должны начинаться с латинской буквы 'L'.
    Пример
    LMarkSumm (сумма баллов), LObjectCount (количество объектов).
  • Имена доменов должны начинаться с латинской буквы 'T'. В именах доменов допустимы пробелы. Рекомендуется к имени домена добавлять слово 'domain' (через пробел), а для обязательных доменов 'required domain' (через пробел) тогда, когда необходимо исключить возможность использования этих доменов в текстах на PascalScript. Первым словом в имени домена-ссылки должно быть имя класса домена. Исключением являются имена доменов, соответствующих простым типам данных без дополнительных ограничений. Имена таких доменов могут повторять имена типов языка PascalScript (Integer, Boolean, Float).
    Пример
    Имя Класс домена Наименование
    TPrice domain Вещественный домен Цена
    TWeight required domain Целочисленный домен Вес (обязательный)
    Boolean Логический Логический
    TClassMember required domain Ссылка домен Член класса
  • Имена элементов перечислений должны иметь префикс из двух или трех символов, идентифицирующий соответствующий домен-перечисление. Префикс записывается строчными буквами. Например,
    Пример
    Имя Наименование
    для домена TExamKind (вид испытания)
    ekTest зачет
    ekExam экзамен
    ekDifTest дифференцированный зачет
    для домена TAggregateKind (вид агрегата)
    agCount количество
    agSumm сумма
    agAverage среднее значение
    Настоятельно рекомендуется давать уникальные имена элементов перечислений в пределах всей системы.

2. Стилевое оформление исходного кода

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


2.1. Использование строк, пробелов и отступов

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

Пробелы, запрещенные к использованию:

  • До или после точки "."
  • Между именем вызываемого метода и открывающей скобкой "("
  • После открывающей скобки "(" или перед закрывающей ")"
  • Перед точкой с запятой ";"
  • Перед двоеточием ":"
  • Перед запятой ","

Двоеточие для всех объявлений переменных не должно содержать перед собой пробелов и иметь один пробел после перед именем типа.

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

Существует несколько исключений из этого правила. Зарезервированные слова var, begin и end, относящиеся к программному блоку вцелом, всегда должны примыкать к левой границе. Код внутри блока begin..end должен иметь отступ два символа.

Все строки должны быть ограничены 80 столбцами. Строки, длиннее чем 80 столбцов должны быть разделены и перенесены. Все перенесенные строки должны быть выровнены по первой строке и иметь отступ в два символа. Зарезервированное слово begin всегда должно находиться на своей отдельной строке.

Нельзя переносить строки в тех местах, где не допускаются пробелы, например между именем метода и открывающей скобкой. Никогда нельзя помещать зарезервированное слово begin на строку, содержащую другой код.


2.2. Оформление объявлений и операторов

Все переменные с их типами должны быть объявлены на различных строках.

Простые операторы содержат одну точку с запятой. Если Вам необходимо разделить оператор, то перенесите продолжение оператора на следующую строку с отступом в два пробела.
Пример
  MyValue :=
    MyValue + (SomeVeryLongStatement / OtherLongStatement);

Составные операторы всегда заканчиваются точкой с запятой.
Пример
1begin
2  MyStatement;
3  MyNext Statement;
4  MyLastStatement;
end;

Каждое присвоение и каждое выражение должно располагаться на разных строках.

Оператор "if"

Оператор if всегда должен располагаться по крайней мере на двух строках
Неправильно
if A < B then DoSomething; 
Правильно
if A < B then
  DoSomething;
В случае составного оператора необходимо поместить каждый оператор на новую строку.
Неправильно
1  if A < B then begin
2    DoSomething;
3    DoSomethingElse;
4  end else begin
5    DoThis;
6    DoThat;
7  end;
Правильно
1  if A < B then
2  begin
3    DoSomething;
4    DoSomethingElse;
5  end
6  else
7  begin
8    DoThis;
9    DoThat;
  end;
Все остальные варианты расположения операторов не рекомендуются и не одобряются, хотя и являются синтаксически правильными.

Оператор "for"

Неправильно
1  for i := 0 to 10 do begin
2    DoSomething;
3    DoSomethingElse;
4  end;
Правильно
1  for i := 0 to 10 do
2  begin
3    DoSomething;
4    DoSomethingElse;
5  end;
6
7  for I := 0 to 10 do
8    DoSomething;

Оператор "while"

Неправильно
1  while x < j  do begin
2    DoSomething;
3    DoSomethingElse;
  end;
Правильно
1  while x < j do
2  begin
3    DoSomething;
4    DoSomethingElse;
5  end;
6
7  while x < j do
8    Something;

Оператор "repeat..until"

Правильно
1  repeat
2    x := j;
3    j := UpdateValue;
4  until j > 25;

Оператор "case"

Несмотря на то, что существует множество синтаксически правильных конструкций, одобренной и рекомендованной считается следующая:
Правильно
01  case LCode of
02    1, 3:
03      begin
04        Incr := FIncrement + 1;
05        FinalIncr := FIncrement div FLineDiv;
06        Count := FLineDiv;
07      end;
08    2, 4:
09      begin
10        Incr := FPageIncrement;
11        FinalIncr := Incr + 1;
12        Incr := Incr div FPageDiv;
13        Count := FPageDiv;
14      end;
15  else
16    begin
17      Count := 0;
18      Incr := 0;
19      FinalIncr := 0;
20    end;
  end;

Оператор "try"

Несмотря на то, что существует множество синтаксически правильных конструкций, одобренной и рекомендованной считается следующая:
Правильно
01try
02  try
03    EnumItems(CurrentThreadID, LDisable, 0);
04    Result := TaskList;
05  except
06    EnableItems(TaskList);
07    raise;
08  end;
09finally
10  TaskList := SaveList;
11  TaskActive := SaveActive;
end;