стандарт стилевого оформления исходного кода delphi

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

Данный документ содержит рекомендации к оформлению кода, призванные упростить поддержку проектов, написанных на языке программирования Delphi. Рекомендации максимально приближены к стандартам Borland и Embarcadero, разработчиков компиляторов языка. Материал содержит и авторские рекомендации, которые основаны на анализе продуктов, принадлежащих данным компаниям.

Целью документа является более-менее четкое описание правил оформления исходного кода при создании программ. Поскольку Delphi часто используется как средство обучения базовым навыкам программирования, важно выработать у обучающегося хороший стиль написания кода. По этой причине материал, изложенный в данном источнике, в первую очередь предназначен для учащихся высших, средних специальных учебных заведений и учреждений среднего общего образования. Автор, сам являясь студентом, создал его и для личного пользования.

Содержание данного материала основывается на статье «Object Pascal Style Guide» Чарльза Калверта на ресурсе Embarcadero Developer Network и в значительной части представляет ее перевод с некоторыми изменениями. Так как статья была опубликована давно, такие изменения необходимы для соответствия рекомендаций особенностям современной разработки. Однако материал документа несколько шире, чем материал статьи: была принята попытка исправить обозначенные пользователями недочеты Чарльза, а также дополнить подготовленную им информацию.

Язык программирования Delphi постоянно развивается. С ним растет и объем материала, который необходимо охватить в рамках руководства по оформлению кода. Важной задачей является сохранение актуальности и гарантия корректности изложенных рекомендаций, поэтому приветствуется любая помощь с редактирование данного документа.

Источник

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

Object Pascal является замечательно спроектированным языком. Одним из его многочисленных достоинств является легкая читабельность. Предлагаемый стандарт позволит еще более повысить легкость чтения кода Object Pascal. Следование довольно простым соглашениям, приведенным в этом стандарте, позволит разработчикам понять, что унифицированное оформление намного повышает читабельность и понятность кода. Использование стандарта намного облегчит жизнь во время этапов разработки и тестирования, когда довольно часто приходится подменять друг друга и разбираться в чужом коде.

Процесс перехода с собственного стиля оформления на предлагаемый может оказаться непростым, но человеческий мозг довольно легко адаптируется к стандартам и находит пути для быстрого запоминания предлагаемых правил. В дальнейшем, следование стандарту не вызывает затруднений. Для более комфортабельного перехода на этот стандарт предагается воспользоваться свободно распространяемой утилитой для форматирования исходных текстов «delforexp».

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

Этот документ не является попыткой определить грамматику языка Object Pascal. Например, если Вы попытаетесь поставить точку с запятой перед выражением else, то компилятор не позволит Вам этгого сделать. Этот документ говорит Вам, как нужно поступать, когда есть возможность выбора из многих вариантов при оформлении Вашего исходного кода.

ФАЙЛЫ ИСХОДНОГО КОДА

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

Именование исходных файлов

Язык Object Pascal поддерживает длинные имена файлов. Если при создании имени Вы используете несколько слов, то необходимо использовать заглавную букву для каждого слова в имени: MyLongName.pas. Этот стиль оформления известен как InfixCaps или CamelCaps. Расширения файлов должны быть в нижнем регистре. Исторически, некоторые исходные файлы Delphi именуются по шаблону 8.3, но в настоящее время разработчики не обязаны придерживаться этого ограничения.

Если Вы осушествляете перевод заголовочных файлов C/C++, то паскалевский эквивалент должен иметь тоже самое имя и расширение PAS. Например Windows.pas. Если правила грамматики языка Object Pascal требуют объединения нескольких транслированных файлов в один, то используйте имя того файла, в который Вы вкладываете остальные. Например: если WinBase.h вкладывается в Windows.h, то результирующее имя будет Windows.pas.

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

Организация исходных файлов

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

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

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

Секции определения типов и констант Вы можете располагать относительно друг друга как Вам угодно. Секция реализации должна начинаться с ключевого слова implementation, затем объявление используемых модулей (Uses clause), затем любые включение файлов или другие директивы.

Копирайт и комментарий

Пример заголовка для модуля:

Каждый исходный файл должен содержать объявление модуля. Слово unit является ключевым, поэтому оно должно быть написано в нижнем регистре. Имя модуля может содержать символы как в верхнем, так и в нижнем регистре и должно быть таким же, как и имя используемое для этого файла операционной системой. Например:

Объявление используемых модулей

Внутри модуля объявление используемых модулей должно начинаться со слова uses в нижнем регистре. Затем следуют наименования модулей с сохранением регистра символов:

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

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

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

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

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

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

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

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

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

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

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

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

Именование классов и интерфейсов

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

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

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

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

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

Именование локальных переменных

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

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

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

Использование пустых строк

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

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

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

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

Существует несколько исключений из этого правила. Зарезервированные слова unit, uses, type, interface, implementation, initialization и finalization всегда должны примыкать к левой границе. Также должны быть отформатированы финальный end и end, завершающий исходный модуль. В файле проекта выравнивание по левой границе применяется к словам program, главным begin и end. Код внутри блока begin..end должен иметь отступ два символа.

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

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

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

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

КОММЕНТАРИИ

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

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

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

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

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

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

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

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

КЛАССЫ

Структура тела класса

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

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

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

ИНТЕРФЕЙСЫ

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

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

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

Структура тела интерфейса

ОПЕРАТОРЫ

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

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

Составные операторы всегда заканчиваются точкой с запятой.

Присвоения и выражения

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

Объявление локальных переменных

Локальные переменные должны иметь стиль Camel Caps. Для локальных переменных префикс F не требуется. Все переменные с их типами, особенно поля класса, должны быть объявлены на различных строках.

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

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

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

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

Оператор repeat until

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

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

ДОПОЛНЕНИЯ

В этой части собраны дополнения, которые не вошли в стандарт Borland. Эти дополнения взяты из правил JCL и опыта российских разработчиков.

Зарезервированные слова var, const и type всегда пишутся на новой строке и не допускают появления на этой же строке какого-либо текста.

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

Директивы условной компиляции

Все директивы условной компиляции должны быть собраны в одном модуле ХХX.INC. Этот файл предназначен для определения глобальных директив. Оператор include должен быть помещен между ключевыми словами unit и interface. Никто не может мождифицировать файл ХХX.INC по собственному желанию.

Все строковые ресурсы должны иметь вид «Rs»[Category][Name]. [Category] должно быть аббревиатурой или названием категории кода, где используется строка. [Name] должно быть именем строки ресурса. Например, конструктор TJclCriticalSectionEx.CreateEx вызывает исключительную ситуацию при ошибке инициализации. Сообщение об ошибке объявляется в глобальном модуле ХХXResources.pas с именем RsynchInitCriticalSection.

Все строки должны быть исключены из кода и заменены на константы. Исключением из этого правила являются строки, которые являются какими-либо командами или от них будет зависеть поведение экземпляров класса. Такие строки должны быть явно объявлены в каком-либо из методов класса.

Все исключения должны начинаться с префикса EХХХ. Все исключения должны быть отнаследованны от класса ENхError. При возбуждении исключительной ситуации предпочтительным является ее создание с помощью метода CreateRes:

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

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

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

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

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

Инициализация глобальных переменных

Глобальные переменные, как и члены класса всегда инициализируются нулем. Это трудно для понимания в случае разных типов. Например Integer инициализируется в 0, а pointer в nil. Для этого рекомендуется указывать в комментарии как инициализируется переменная.

Несмотря на то, что глобальные переменные разрешены языком Object Pascal, используйте их лишь в самых крайних случаях.

Источник

Стандарты написания исходного кода в Delphi. СОГЛАШЕНИЕ ОБ ИМЕНОВАНИЯХ

Delphi site: daily Delphi-news, documentation, articles, review, interview, computer humor.

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

Имя класса должно быть именем существительным или фразой с именем существительным. Имена интерфейсов или классов должны отражать главную цель их создания.

Правильно:
AddressForm
ArrayIndexOutOfBoundsException

Неправильно:
ManageLayout (глагол)
delphi_is_new_to_me (подчеркивание)

2.1. ИМЕНОВАНИЕ МОДУЛЕЙ

Наименование модуля должно построено быть по принципу: «u» + «Имя формы». Если модуль не содержит формы (модуля данных), то первая литера «u» сохраняется, далее идет функциональное наименование модуля.

2.2. ИМЕНОВАНИЕ ФОРМ И МОДУЛЕЙ ДАННЫХ

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

Главный модуль данных приложения именуется » MainDM «. Главный модуль содержит глобальные параметры подключения к БД, обеспечивает функции для доступа к таблицам с настройками.

Рекомендуется, чтобы каждой форме соответствовал только один модуль данных, ссылающийся только на главный модуль данных приложения. Не допускается наличие у каждого модуля данных своего подключения к БД, если логикой приложения это отдельно не предусмотрено.

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

2.3. ИМЕНОВАНИЕ КЛАССОВ И ИНТЕРФЕЙСОВ

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

2.4. ИМЕНОВАНИЕ ПОЛЕЙ

Правильно
FMyString: string;

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

Исключение для Венгерской нотации делается в случае объявления перечислимого типа:
TBitBtnKind = (bkCustom, bkOK, bkCancel, bkHelp,
bkYes, bkNo, bkClose, bkAbort, bkRetry,
bkIgnore, bkAll);
bk обозначает ButtonKind

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

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

2.5. ИМЕНОВАНИЕ МЕТОДОВ

Правильно:
ShowStatus
DrawCircle
AddLayoutComponent

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

Например:
GetHeight, SetHeigh

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

Например:
IsResizable, IsVisible

Не допускается смешивание функций из разных пар (например Get/Save – это неправильно).

2.6. ИМЕНОВАНИЕ ПЕРЕМЕННЫХ

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

Переменные, содержащие двоичные значения (флаги) могут именоваться либо с префиксом Is +имя свойства, либо с префиксом Flg +имя свойства, не рекомендуется использовать префикс «not», выражающий отрицание, всегда следует в таком случае заменять его на » Is «, т.е. не использовать » NotFound «, лучше » IsFound «.

Рекомендуется использовать префикс » N » если переменная представляет количество чего-либо, например NItems ; если переменная представляет номер, то окончание » No «, например » RecordNo «.

2.7. НОТАЦИЯ (ПРЕФИКСЫ) ДЛЯ ИМЕНОВАНИЯ ПЕРЕМЕННЫХ (ЭКЗЕМПЛЯРОВ ОБЪЕКТОВ) В ЗАВИСИМОСТИ ОТ ТИПА

Однако опыт разработки свидетельствует, что использование префиксов для именования переменных является эффективным способом стандартизации кода и очень распространено программистами, в том числе, и работающими с Borland Delphi.

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

Смешивание различных стилей именования переменных в одном участке кода допускается, хотя и настоятельно не рекомендуется.

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

2.8. ИМЕНОВАНИЕ ГЛОБАЛЬНЫХ КОНСТАНТ

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

Допускается именование глобальных констант в верхнем регистре, для разделения слов в данном случае следует использовать знак подчеркивания «_».

Правильно:
cnstEvaluationMode = true;
EVALUATION_MODE = true;

Неправильно:
EvaluationMode (Со взгляда на переменную нельзя определить, константа это или нет)
EVALUATIONMODE (Сложно прочитать)

2.9. ЗАРЕЗЕРВИРОВАННЫЕ СЛОВА

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

2.10. ОБЪЯВЛЕНИЕ ТИПОВ И ЭКЗЕМПЛЯРЫ ПЕРЕМЕННЫХ ОПРЕДЕЛЕННЫХ ТИПОВ

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

2.11. ПЕРЕЧИСЛИМЫЕ ТИПЫ

TSongType = (stRock, stClassical, stCountry, stAlternative, stHeavyMetal, stRB);

2.12. СТРОКОВЫЕ РЕСУРСЫ

Если проект подлежит локализации, все строки должны быть исключены из кода и заменены константами. Исключением из этого правила являются строки, которые являются какими-либо командами или от них будет зависеть поведение экземпляров класса. Такие строки должны быть явно объявлены в каком-либо из методов класса.

2.13. ИСКЛЮЧЕНИЯ

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

Copyright © 2004 Вячеслав Колдовский Специально для Delphi Plus

Источник