Информатизация: Стилевое оформление исходного кода в Delphi

Вступление
   Я думал первую статью начать с описания проекта, но решил описать сначала стилевое оформление исходного кода в Delphi. Думаю причина ясна - сначала учимся грамотно писать =). Статья должна быть полезна как для начинающих, так и для опытных программистов. При написании статьи старался приводить примеры, поскольку написанное это хорошо, а увиденное лучше =).
Object Pascal - замечательно спроектирован язык. Одним из его многочисленных достоинств является легкая читабельность. Описанный ниже стандарт позволит еще больше повысить легкость чтения кода Object Pascal. Унифицированный стиль написания исходного кода повышает читабельность и понятность. Да можно проигнорировать статью и писать как попало, но это лишь действует до некоторого времени, когда проект разрастается и строк кода все больше и больше – приходит момент когда все в куче, и разобраться в этом невозможно. Или представьте ситуацию - вы пришли на новую работу и вам дали недоделанный проект, при написании которого человек понятия не имел что такое форматирование текста вообще, тогда придется худо и вы его будете вспоминать не раз =).

   Естественно переход с собственного стиля оформления на предлагаемый может оказаться непростым, но рано или поздно это надо делать. Есть утилита которая может посодействовать более комфортабельно перейти на этот стандарт. Называется она "delforexp" (Доступна для Delphi 2/3/4/5/6/7/9/2007). В среде Delphi 2010 есть уже встроенный свой инструмент форматирования исходного кода.

   Кстати в компании Borland, на Web-сайте компании Borland, на CD, DVD купленных у компании Borland, везде где есть исходный код, стандарт форматирования является законом.

   Данный документ не является попыткой определить грамматику языка Object Pascal. В нем приводятся базовые примеры как можно поступить при оформлении исходного кода.

Файлы исходного кода (Наверх)   Исходный код Object Pascal подразделяется на модули и файлы проекта, которые подчиняются одинаковым соглашениям. Файл проекта Delphi имеет расширение dpr. Этот файл является главным исходным файлом для всего проекта. Любые модули, используемые в проекте, всегда будут иметь расширение pas. Дополнительные файлы, используемые в проекте могут играть важную роль, но эта глава описывает форматирование только pas и dpr файлов. Более подробно о расширениях файлов можно прочитать в статье: Описание типов файлов в среде Delphi.

Именование файлов (Наверх)
   Язык Object Pascal поддерживает длинные имена файлов. Если при создании имени файла Вы используете несколько слов, то необходимо использовать заглавную букву для каждого слова в имени, например: MyFirstProjectName.pas. Такой стиль оформления известен как InfixCaps или CamelCaps. Расширения файлов должны быть в нижнем регистре.

   Все файлы модулей которые созданы в какой либо организации, например: ХХХ должны иметь префикс ХХХ

Организация исходных файлов (Наверх)
   Все модули Object Pascal могут содержать следующие элементы в определенном порядке:

Информация о правах (Copyright/ID);
Имя модуля (Unit Name);
Секцию интерфейса (Interface section);

Подключаемые модули

Объявление классов и интерфейсов

Дополнительные определения (Additional defines);

Реализаця (Implementation)

Объявление используемых модулей и директив (Uses clause);
Исходный код;

Закрывающий оператор и точку (end.) (A closing end and a period).

Для визуального разделения элементов между ними должна быть хотя бы одна пустая строка.

При создании нового проекта – среда разработки генерирует исходный код, пример которго приведен ниже:

unit Unit1;

interface
uses
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
Dialogs;

type
TForm1 = class(TForm)
private

{ Private declarations }
public
procedure TForm1.Inp(a:integer);
end;

var
Form1: TForm1;

implementation

{$R *.dfm}
procedure TForm1.Inp(a:integer);
begin
...
end;

end.

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

Информация о правах (копирайт) (Наверх)
Должен содержать следующие пункты:

Назначение модуля;
Копирайт;
Разработчик;
Дата последней модификации для исполняемой версии

Он должен выглядеть примерно следующим образом:

{*******************************}
{                                                              }
{                   Модуль ХХХUnit             }
{             Copyright (c) 2010 ХХХ }
{                     отдел/сектор                   }
{                                                              }
{     Разработчик: x.xxxxxxxx               }
{     Редактирован: дата                        }
{                                                              }
{*******************************}

Имя модуля (Наверх)
   Оно начинается с ключевого слова unit. Имя модуля может содержать символы как в верхнем, так и в нижнем регистре. Например: unit XXXModule1; В результате этот модуль будет назван XXXModule1.pas при сохранении.

Секция интерфейса (Наверх)
   Она состоит из определения подключаемых модулей, описания типов, констант, массивов, переменных:

Подключаемые модули(Наверх)
   Внутри модуля объявление используемых модулей должно начинаться со слова uses (в нижнем регистре). Затем следуют наименования модулей с сохранением регистра символов.
Каждый используемый модуль должен отделяться от следующего с помощью запятой. Объявление используемых модулей должно заканчиваться точкой с запятой. Список используемых модулей необходимо располагать на следующей строке после слова uses. Если используются модули из разных проектов или производителей, то необходимо сгруппировать модули по проектам или производителям и каждую новую группу начинать с новой строки и прокомментировать каждую группу:

uses
Windows, SysUtils, Classes, Graphics, Controls, Forms, TypInfo, // модули Delphi
XХХMyUnit1, ХХXMyUnit2; // модули ХХХ

Если список используемых модулей не умещается по ширине в 80 символов (в редакторе кода есть вертикальная полоса, которая показівает границу в 80 символов), то его необходимо перенести на следующую строку.

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

Правильно:

AddressForm
ArrayIndexOutOfBoundsException

Неправильно:

ManageLayout //глагол
delphi_is_new_to_me //подчерк

Объявление класса и типов начинается с двух пробелов, затем идет идентификатор класса(его имя) с префиксом Т.

Следом за идентификатором класса идет пробел, знак равенства, пробел и слово class в нижнем регистре:

TMyClass = class

Если необходимо определить родителя класса, то следует добавить открывающую скобку, имя класса - родителя и закрывающую скобку:

TMyClass = class(TObject)

Объявления областей видимости начинаются с двух пробелов и, следовательно, области видимости распологаются на одном уровне с идентификатором класса:

TMyClass = class(TObject)
private
protected
public
published
end;

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

TMyClass = class(TObject)
private
    FMyData: Integer;
    function GetData: Integer;
procedure SetData(Value: Integer);
public
published
    property MyData: Integer read GetData write SetData;
end;

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

Ключевое слово type размещается без отступов, перечисление типов начинается с новой строки:

uses
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
Dialogs;

type
TForm1 = class(TForm)
private
{ Private declarations }
public
procedure TForm1.Inp(a:integer);
end;
var
Form1: TForm1;

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

implementation

uses MyUnit.pas

{$R *.dfm}

procedure Inp(a:integer);
begin
...
end;

Закрывающий оператор и точку (end.) (A closing end and a period) (Наверх)
И конечно же в конце всего этого долен стоять оператор end. – что сведетельствует о окончании модуля.

Соглашение об именовании (Наверх)
Исключая зарезервированные слова и директивы, которые всегда пишутся в нижнем регистре, все идентификаторы Object Pascal должны использовать InfixCaps (Каждое слово начинается с большой буквы):

MyIdentif, MyFTPClass, NewModuleName;

   Самое главное исключение для всех правил состоит в использовании оттранслированных заголовочных файлов С/С++. В этом случае всегда используются соглашения, принятые в файле источнике. Например будет использоваться WM_LBUTTONDOWN, а не wm_LButtonDown.

Именование (Наверх)
   При именовании полей всегда необходимо использовать InfixCaps. Объявлять переменные только в приватных частях и использовать свойства для доступа к переменным. Для переменных использовать префикс F.

   Имена всех локальных переменных должны подчиняться тем же правилам, которые установлены для именования полей, исключая префикс F.

   В имени метода всегда должна содержаться команда к действию или глагольная фраза:

Правильно:

ShowStatus
DrawCircle
AddLayoutComponent

Неправильно:

MouseButton; //Существительное, не описывает функцию
drawCircle; //Начинается с маленькой буквы
add_layout_component; //Используются символы подчерка
ServerRunning; //Глагольная фраза, но без команды

Обратите внимание на последний пример (ServerRunning) - непонятно, что делает этот метод, он может быть использован как для запуска сервера (лучше использовать StartServer) так и для проверки работы сервера (лучше использовать IsServerRunning).

Имена процедур или методов для установки/получения значений свойств должны составляться по правилу: для получения - Get+имя свойства; для установки - Set+имя свойства.

Например:

GetHeight, SetHeigh;

Методы для теста/проверки булевских свойств класса должны именоваться с префиксом Is+имя свойства.

Например:

IsResizable, IsVisible, IsServerRunning;

Примечание:

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

Правильно

FMyString: string;

Неправильно

lpstrMyString: string;

Исключение для Венгерской нотации делается в случае объявления перечислимого типа:

TBtnKind = (bkCustom, bkOK, bkCancel, bkHelp,bkYes, bkNo, bkClose, bkAbort, bkRetry,bkIgnore, bkAll);

bk обозначает ButtonKind;

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

   Переменные цикла именуются I и J. Другие случаи использования однобуквенных переменных это S (строка) и R (результат). Однобуквенные имена должны всегда использовать символ в верхнем регистре, но лучше использовать боле значимые имена. Также не рекомендуется использовать переменную l (эль), потому что она похожа на 1 (единица).

Зарезервированные слова (Наверх)
   Зарезервированные слова и директивы должны быть все в нижнем регистре. Производные типы должны начинаться с большой буквы (Integer), однако string - это зарезервированное слово и оно должно быть в нижнем регистре.

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

После блока копирайта;
После декларации пакета;
После секции импорта;
Между объявлениями классов;
Между реализациями методов;

Использование пробелов (Наверх)
Язык Object Pascal является очень легким для понимания языком, поэтому нет особой необходимости в использовании большого количества пробелов. Следующие пункты дадут Вам понимание - в каком случае необходимо использовать пробелы.

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

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

Примеры правильного использования:

function TMyClass.MyFunc(var Value: Integer);
MyPointer := @MyRecord;
MyClass := TMyClass(MyPointer);
MyInteger := MyIntegerArray[5];

Примеры неправильного использования:

function TMyClass.MyFunc( var Value: Integer ) ;
MyPointer := @ MyRecord;
MyClass := TMyClass ( MyPointer ) ;
MyInteger := MyIntegerArray [ 5 ] ;

Использование отступов (Наверх)
   Всегда необходимо использовать два пробела для всех уровней отступа. Другими словами, первый уровень отступает на два пробела, второй на четыре и так далее. Можно настроить табуляцию на ширину в 2 пробела и пользоваться табуляцией.

   Существует несколько исключений из этого правила. Зарезервированные слова unit, uses, type, interface, implementation, initialization и finalization, они всегда должны примыкать к левой границе.

   Также должны быть отформатированы финальные end-ы , завершающий исходный модуль и отдельные блоки. В файле проекта выравнивание по левой границе применяется к также к словам program, главным begin и end. Код внутри блока begin-end должен иметь отступ два символа.

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

Правильно

procedure Foo(Param1: Integer; Param2: Integer);

Неправильно

procedure Foo( Param :Integer; Param2:Integer );

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

Правильно

while (LongExpression1 or LongExpression2) do
begin
// DoSomething

// DoSomethingElse;
end;
if (LongExpression1)
or (LongExpression2)
or (LongExpression3) then

Неправильно

while (LongExpression1 or LongExpression2) do begin
// DoSomething

// DoSomethingElse;
end;

В случае с логическими операторами предпочтительнее будет следующий вариант:

if (LongExpression1)
or (LongExpression2)
or (LongExpression3) then

Комментарии (Наверх)
Язык Object Pascal поддерживает два типа комментариев: блочные и однострочные. Общие правила по использованию комментариев могут быть следующими:

Помещайте комментарий недалеко от начала модуля для пояснения его назначения;
Помещайте комментарий перед объявлением класса;
Помещайте комментарий перед объявлением метода;
Избегайте очевидных комментариев: (i := i + 1 // добавить к i единицу);
Помните, что вводящий в заблуждение комментарий хуже чем его отсутствие;
Избегайте помещать в комментарий информацию, которая со временем может быть не верна;
Избегайте разукрашивать комментарии звездочками или другими символами;
Для временных (отсутствующие в релизе) комментариев используйте "TODO".

Блочные комментарии (Наверх)
Object Pascal поддерживает два типа блочных комментариев. Наиболее часто используемый блочный комментарий - это пара фигурных скобок: { }. Команда разработчиков Delphi предпочитает использовать этот комментарий как можно проще и как запасной. Используйте в таких комментариях пробелы для форматирования текста и не используйте символы зведочка "*". При переносе строк необходимо сохранять отступы и выравнивание

Пример из DsgnIntf.pas:

{ TPropertyEditor

Edits a property of a component, or list of components,
selected into the Object Inspector. The property
editor is created based on the type of the
property being edited as determined by the types
registered by...

etc...

GetXxxValue
Gets the value of the first property in the
Properties property. Calls the appropriate
TProperty GetXxxValue method to retrieve the
value.

SetXxxValue Sets the value of all the properties
in the Properties property. Calls the appropriate

TProperty SetXxxxValue methods to set the value. }

В блочный комментарий в большинстве случаев заключается информация о модуле: копирайт, дата модификации и так далее. Блочный комментарий, описывающий метод должен идти перед объявлением метода.

Правильно

{ TMyObject.MyMethod
This routine allows you to execute code. }

procedure TMyObject.MyMethod;
begin
end;

Неправильно

procedure TMyObject.MyMethod;

{******************************************************
TMyObject.MyMethod
This routine allows you to execute code.
*******************************************************}
begin
end;

Второй тип блочного комментария содержит два символа: скобку и звездочку: (* *). Этот тип комментария используется при разработке исходного кода. Его преимуществом является то, что он поддерживает вложенные комментарии, правда комментарии должны быть разного типа. Вы можете использовать это свойство для комментирования больших кусков кода, в котором встречаются другие комментарии:

(* procedure TForm1.Button1Click(Sender: TObject);
begin
DoThis; // Start the process
DoThat; // Continue iteration
{ We need a way to report errors here, perhaps using
a try finally block ??? }
CallMoreCode; // Finalize the process
end; *)

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

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

Пример однострочного строкового комментария:

// Open the table
Table1.Open;

Пример комментария в коде:

if (not IsVisible) then
Exit; // nothing to do
Inc(StrLength); // reserve space for null terminator

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

Классы
Структура тела класса (Наверх)

Тело класса при его декларации подчинено следующей структуре:

Объявление полей;
Объявление методов;
Объявление свойств.

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

Уровни доступа (директивы видимости) (Наверх)
   В Object Pascal существует четыре уровня доступа (директивы видимости) для членов класса: published, public, protected и private - в порядке уменьшения видимости. По умолчанию, уровень доступа - published. В общем, члены класса должны давать наименьший уровень доступа, который подходит для этого члена.
   Например, член, к которому имеют доступ классы из одного модуля должен иметь уровень доступа private. Кроме того, объявляя члены класса с наименьшим уровнем доступа, Вы позволяете компилятору воспользоваться дополнительными возможностями для оптимизации. С другой стороны, если Вы планируете в дальнейшем порождать дочерние классы от Вашего класса, то нужно использовать уровень доступа protected.

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

   Исключая код, вставленный IDE, директивы видимости должны быть объявлены в следующем порядке:

Приватные (скрытые) члены класса (private);
Защищенные члены класса (protected);
Общедоступные члены класса (public);
Публикуемые члены класса (published)

Объявление конструктора (Наверх)
Все методы класса должны быть упорядочены по алфавиту. Однако Вы можете поместить объявления конструктора и деструктора перед всеми остальными методами. Если у класса существует более чем один конструктор и если они имеют одинаковые имена, то они должны располагаться в порядке увеличения числа параметров

Объявление методов (Наверх)
По возможности, объявление метода должно располагаться на одной строке:
Например:

procedure ImageLoad(ImageCount: Integer, y: Integer, w: Integer, h: Integer);

Интерфейсы (Наверх)
Все основные правила форматирования для классов применяются и для форматирования интерфейсов. Интерфейсы декларируются в той же манере, что и классы.

InterfaceName = interface([Inherited Interface])
InterfaceBody
end;

   Отступ для интерфейса должен быть равен двум пробелам. Тело интерфейса имеет отступ четыре пробела. Закрывающий end должен иметь отступ в два пробела. Объявление класса заканчивается точкой с запятой. У интерфейса не существует полей, однако могут присутствовать свойства.

   Все методы интерфейса являются абстрактными и общедоступными, поэтому не требуется включать слова public и abstract в объявление метода.

Структура тела интерфейса (Наверх)
   Тело интерфейса при его декларации подчинено следующей структуре:

Объявление методов интерфейса;
Объявление свойств интерфейса.

Стили для объявления свойств и методов интерфейса аналогичным стилям для класса.

Операторы (Наверх)
Операторы - это одна или более строк кода, разделенных точкой с запятой. Простые операторы имеют одну точку с запятой, а составные (структурированные) состоят из множества простых операторов и могут иметь более чем одну точку с запятой.
Например, простой оператор:

A := B;

Это составной или структурированный оператор:

begin
B := C;
A := B;
end;

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

MyValue :=
MyValue + (SomeStatement / OtherStatement);

Составные операторы(Наверх)
Составные операторы всегда заканчиваются точкой с запятой и имеют несколько простых операторов.

begin
MyStatement;
MyNextStatement;
MyLastStatement;
end;

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

a := b + c;
Inc(Count);

Неправильно

a := b + c; Inc(Count);

Объявление локальных переменных(Наверх)
Как уже было описано выше - локальные переменные должны иметь стиль Camel Caps. Для локальных переменных префикс F не требуется.

var
MyData: Integer;
MyString: string;

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

Объявление массивов(Наверх)
При объявлении массива перед и после квадратных скобок должны стоять пробелы.

type
TMyArray = array [0..100] of Char;

Оператор if(Наверх)
Оператор if всегда должен располагаться по крайней мере на двух строках, на первой - условие, на второй - оператор
Правильно

if A > B then
DoSomething;

Неправильно

if A > B then DoSomething;

В случае составного оператора необходимо поместить каждый оператор на новую строку.
Правильно

if A > B then
begin
DoSomething;
DoSomethingElse;

end
else
begin
DoThis;
DoThat;
end;

Неправильно

if A > B then begin
DoSomething; DoSomethingElse ;
end else begin DoThis; DoThat; end;

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

if I >= 0 then
DoSomething;

Неправильно

if (I >= 0) then
DoSomething;

Оператор for(Наверх)
Оператор for всегда должен располагаться по крайней мере на двух строках, на первой - условие, на второй - оператор.
Правильно

for I := 0 to 10 do
begin
DoSomething;
DoSomethingElse;
end;

for I := 0 to 10 do
DoSomething;

Неправильно

for I := 0 to 10 do begin
DoSomething;
DoSomethingElse;
end;

Оператор while(Наверх)
Оператор while также как и предыдущие операторы должен располагаться на нескольких строках

Правильно

while X > J do
begin
DoSomething;
DoSomethingElse;
end;

while X < J do
Something;

Неправильно

while X > J do begin DoSomething; DoSomethingElse; end;

Оператор repeat until (Наверх)
Также как и все операторы - должен быть записан с новой строки каждый элемент.
Правильно

repeat
X := J;
J := UpdateValue;
until J >= 25;

Оператор case(Наверх)
Несмотря на то, что существует множество синтаксически правильных конструкций, одобренной и рекомендованной считается следующая:
Правильно

case ScrollCode of
SB_LINEUP, SB_LINEDOWN:
begin
    Incr := FIncrement div FLineDiv;
    FinalIncr := FIncrement mod FLineDiv;
    Count := FLineDiv;
end;
SB_PAGEUP, SB_PAGEDOWN:
begin
    Incr := FPageIncrement;
    FinalIncr := Incr mod FPageDiv;
    Incr := Incr div FPageDiv;
    Count := FPageDiv;
end;
else
    Count := 0;
    Incr := 0;
    FinalIncr := 0;
end;

Оператор try(Наверх)
Несмотря на то, что существует множество синтаксически правильных конструкций, одобренной и рекомендованной считается следующая (древовидная структура):
Правильно

try
try
    EnumThreadWindows(CurrentThreadID, @Disable, 0);
    Result := TaskWindowList;
except
    EnableTaskWindows(TaskWindowList);
raise;
end;
finally
TaskWindowList := SaveWindowList;
TaskActiveWindow := SaveActiveWindow;
end;