четверг, 2 февраля 2012 г.

Правила оформления кода на Pascal

В начале файла в комментариях всегда указывается заголовок.
Следует обратить внимание на элементы заголовка:
  • Назначение модуля;
  • Разработчик;
  • Дата последней модификации для исполняемой версии.

Пример:
{************************************************************}
{                                                            }
{                 Модуль ХХХ                                 }
{               отдел/сектор                                 }
{                                                            }
{  Разработчик: ХХ ХХ                                        }
{  Модифицирован: 25 июня 2001                               }
{                                                            }
{************************************************************}

unit Buttons;




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


Объявление используемых модулей
Внутри модуля объявление используемых модулей должно начинаться со слова uses в нижнем регистре. Затем следуют наименования модулей с сохранением регистра символов:
uses MyUnit;
Каждый используемый модуль должен отделяться от следующего с помощью запятой. Объявление используемых модулей должно заканчиваться точкой с запятой. Список используемых модулей необходимо располагать на следующей строке после слова uses. Если используются модули из разных проектов или производителей, то необходимо сгруппировать модули по проектам или производителям и каждую новую группу начинать с новой строки и снабжать комментариями:
uses
 Windows, SysUtils, Classes, 
 Graphics, Controls, Forms, TypInfo // модули Delphi
 , XХХMyUnit1, ХХXMyUnit2;  // модули ХХХ

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


Объявление классов и интерфейсов
Объявление класса начинается с двух пробелов, затем идет идентификатор класса с префиксом Т в нотации InfixCaps. Ни в коем случае в исходных файлах Object Pascal нельзя использовать табуляцию:
TMyClass
Следом за идентификатором класса идет пробел, знак равенства, пробел и слово 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;

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

СОГЛАШЕНИЕ ОБ ИМЕНОВАНИЯХ 

Исключая зарезервированные слова и директивы, которые всегда пишутся в нижнем регистре, все идентификаторы Object Pascal должны использовать InfixCaps:
MyIdentifier MyFTPClass

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


Именование переменных
При именовании переменных всегда необходимо использовать InfixCaps. Имена переменных должны явно указывать на назначение той или иной переменной. Следует избегать имен переменных из одной буквы. Исключение составляют переменные, используемые для указания индексов в цикле for. Для счетчика использовать переменные с именами i,j,k. Для указания координат точек  допустимо использовать имена переменных x,y.
Запрещается объявлять переменные с одинаковыми именами в глобальном разделе объявления переменных и в локальным разделе внутри процедур и функций.

ИСПОЛЬЗОВАНИЕ ПРОБЕЛОВ


Использование пустых строк
Пустые строки могут повысить читабельность путем группирования секций кода, которые логически связаны между собой. Пустые строки должны использоваться в следующих местах:
  • После блока копирайта;
  • После декларации пакета;
  • После секции импорта;
  • Между объявлениями классов;
  • Между реализациями методов;
Использование пробелов
Язык 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 ] ;
Использование отступов
Всегда необходимо использовать два пробела для всех уровней отступа. Другими словами, первый уровень отступает на два пробела, второй на четыре и так далее. Никогда не используйте символы табуляции.
Существует несколько исключений из этого правила. Зарезервированные слова unit, uses, type, interface, implementation, initialization и finalization всегда должны примыкать к левой границе. Также должны быть отформатированы финальный end и end, завершающий исходный модуль. В файле проекта выравнивание по левой границе применяется к словам program, главным begin и end. Код внутри блока begin..end должен иметь отступ два символа.
Перенос строк
Все строки должны быть ограничены 80 столбцами. Строки, длиннее чем 80 столбцов должны быть разделены и перенесены. Все перенесенные строки должны быть выровнены по первой строке и иметь отступ в два символа. Выражение begin всегда должно находиться на своей отдельной строке.
Пример: 
Правильно

function CreateWindowEx(dwExStyle: DWORD;
  lpClassName: PChar; lpWindowName: PChar;
   dwStyle: DWORD; X, Y, nWidth, nHeight: Integer;
   hWndParent: HWND; hMenu: HMENU; hInstance: HINST;
   lpParam: Pointer): HWND; stdcall;

Никогда не разрывайте строку между параметром и его типом, кроме параметров, перечисляемых через запятую. Двоеточие для всех объявлений переменных не должно содержать перед собой пробелов и иметь один пробел после перед именем типа.
Правильно
procedure Foo(Param1: Integer; Param2: Integer);
Неправильно
procedure Foo( Param :Integer; Param2:Integer );
Нельзя переносить строки в тех местах, где не допускаются пробелы, например между именем метода и открывающей скобкой или между именем массива и открывающей квадратной скобкой. Никогда нельзя помещать выражение begin на строку, содержащую другой код.
Неправильно
while (LongExpression1 or LongExpression2) do begin
  // DoSomething
  // DoSomethingElse;
end;

Правильно
while (LongExpression1 or LongExpression2) do 
begin
  // DoSomething
  // DoSomethingElse;
end;
if (LongExpression1) or 
  (LongExpression2) or 
  (LongExpression3) then
В случае с логическими операторами предпочтительнее будет следующий вариант:
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

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

ОПЕРАТОРЫ


Операторы - это одна или более строк кода, разделенных точкой с запятой. Простые операторы имеют одну точку с запятой, а составные могут иметь более чем одну точку с запятой и, таким образом, состоят из множества простых операторов.
Это простой оператор:
A := B;
Это составной или структурированный оператор:
begin
  B := C;
  A := B;
end;
Простые операторы
Простые операторы содержат одну точку с запятой. Если Вам необходимо разделить операторы, то перенесите продолжение оператора на следующую строку с отступом в два пробела:
MyValue :=
  MyValue + (SomeVeryLongStatement / OtherLongStatement);
Составные операторы
Составные операторы всегда заканчиваются точкой с запятой.
begin
  MyStatement;
  MyNext Statement;
  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 i := 0 to 10 do begin
    DoSomething; 
    DoSomethingElse;
  end;

Правильно
  for i := 0 to 10 do
  begin
    DoSomething;
    DoSomethingElse;
  end;

  for I := 0 to 10 do
    DoSomething;

Оператор while
Неправильно
  while x < j  do begin
    DoSomething;
    DoSomethingElse;
  end;

Правильно
  while x < j do
  begin
    DoSomething;
    DoSomethingElse;
  end;   
  while x < j do
    Something;

Оператор 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;





Const, Var и Type
Зарезервированные слова var, const и type всегда пишутся на новой строке и не допускают появления на этой же строке какого-либо текста.
Правильно
type
  TMyType = Integer;

const
  MyConstant = 100;

var
  MyVar: Integer;

Неправильно
type TMyType = Integer;

const MyConstant = 100;

var MyVar: Integer;

Процедуры должны иметь только по одной секции type, const и var в следующем порядке:

procedure SomeProcedure;
type
  TMyType = Integer;
const
  ArraySize = 100;
var
  MyArray: array [1..ArraySize] of TMyType;
begin
  ...
end;



Категории и разделение алгоритмов

В секции реализации каждая подкатегория или класс должен разделяться строкой, состоящей из символов равенства (=), закомментированных однострочным комментарием и пустой строкой перед и после группы функций:

//=================================================

procedure GetLastUserName(var ZUser: string);
begin
...
end;
procedure GetLastDatabase(var ZDatabase: string);
begin
...
end;

//==================================================

Каждая функция из одной группы или методы класса должны разделяться между собой строкой, состоящей из символов минуса (-), закомментированных однострочным комментарием и пустой строкой перед и после функции или метода:

//==================================================

procedure GetLastUserName(var ZUser: string);
begin
...
end;

//--------------------------------------------------

procedure GetLastDatabase(var ZDatabase: string);
begin
...
end;

//==================================================


Оригинальная версия статьи расположена на http://citforum.ru/programming/delphi/style_delphi/

Комментариев нет:

Отправить комментарий

Подписаться на: Комментарии к сообщению (Atom)