12167

Рекомендации по оформлению исходного кода Delphi

Лекция

Информатика, кибернетика и программирование

Рекомендации по оформлению исходного кода Delphi Цель Повысить читаемость исходного кода разрабатываемого программистами. Сфера приложения и определения Рассматриваются файлы содержащие исходный код на языке Object Pascal то есть файлы проекта и файлы модулей. Даютс

Русский

2013-04-24

95.72 KB

5 чел.

Рекомендации по оформлению исходного кода Delphi

Цель

Повысить читаемость исходного кода, разрабатываемого программистами.

Сфера приложения и определения

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

Под объектом далее будем понимать не объект в смысле Object Pascal, а любую сущность языка –тип, переменную, модуль, процедуру –имеющую собственный идентификатор. Заметим, что идентификаторы разных объектов в общем случае не обязаны быть различными.

Общие требования

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

В исходных файлах не следует использовать табуляцию.

Все ключевые слова пишутся в нижнем регистре. Например if, while, platform, string, deprecated.

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

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

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

Все строки должны быть исключены из кода и заменены константами.

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

Использование отступов

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

Перенос строк

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

Идентификаторы

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

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

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

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

Не рекомендуется использовать переменную l (эль), потому что она похожа на 1 (единица).

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

Желательно, чтобы последнее слово в названии объекта давало представление о типе. Например: AuthorsQuery, GoodsDataSource, ParameterEdit, PropertiesFormClass.

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

Строковые ресурсы

Все строковые ресурсы должны иметь вид Rs+КатегорияИмя

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

Комментарии

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

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

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

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

Файлы исходного кода

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

Рекомендуется именовать модули проекта ИмяМодуля+U.

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

Структура исходного файла

Все модули Object Pascal могут содержать следующие элементы в определенном порядке:

  •  Заголовок
  •  Назначение модуля
  •  Права
  •  Информацию о разработчиках
  •  Информацию об изменениях в модуле
  •  Имя модуля
  •  Секцию интерфейса
  •  Объявление используемых модулей
  •  Определения типов, констант, переменных
  •  Определения классов
  •  Определения процедур и функций
  •  Определения констант и переменных –экземпляров классов
  •  Секцию реализации
  •  Объявление используемых модулей
  •  Определения внутренних типов, констант, переменных
  •  Определения внутренних классов
  •  Реализацию процедур и функций
  •  Реализацию методов классов
  •  Секцию инициализации
  •  Секцию завершения

Заголовок модуля оформляется, как комментарий.

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

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

В случае необходимости, можно напрямую переопределить глобальные

директивы компилятора. Следует помнить, что переопределяющие директивы должны

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

переопределением.

В случае, если директива компилятора существует в двух вариантах, как например {$I-} и {$IOCHECKS OFF}, следует использовать второй вариант, как более понятный.

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

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

Объявление типов

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

Идентификатор типа начинается с префикса T, включая классы. Идентификаторы исключений начинаются с префикса E.

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

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

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

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

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

Пример:

 TMyClass = class(TObject)

private

FMyData: Integer;

function GetData: Integer;

procedure SetData(Value: Integer);

public

published

property MyData: Integer read GetData write SetData;

end;

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

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

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

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

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

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

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

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

Именование методов

В имени метода всегда должна содержаться команда к действию или глагольная фраза. Методы для установки и получения значений свойств должны именоваться по правилу: для получения - Get+ИмяСвойства; для установки - Set+ ИмяСвойства.

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

Определение функций, процедур и методов

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

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

Объявление параметров

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

  •  Комбинируйте формальные параметры одного типа в одно выражение
  •  Не используйте префикс А, кроме случаев, когда вызывается метод класса, который работает со свойством, которое имеет идентичное имя
  •  Придерживайтесь следующего порядка в параметрах: сначала входные параметры, затем входные/выходные, затем выходные. Параметры, имеющие значение по умолчанию по правилам Object Pascal помещаются в конец списка
  •  Используйте const для параметров, которые не изменяются при работе вызываемых методов, процедур или функций.
  •  Используйте out для параметров, которые являются выходными параметрами и их значение при работе процедуры или функции никак не учитывается.

Локальные процедуры

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

Операторы

Не допускается объединение нескольких операторов на одной строке. Операторные скобки begin..end следует располагать на отдельной строке. Также на отдельной строке располагаются операторы for..do, while..do, части оператора repeat..until, части оператора try..finally|except..end.

Оператор goto

Оператор goto не используется.

Оператор if

Оператор if всегда располагается, по крайней мере, на двух строках:

if <условие> then

 <действие>;

 ñëó÷àå, åñëè èñïîëüçóåòñÿ êîíñòðóêöèÿ if-then-else;, следует использовать такую конструкцию:

if <условие>

then

 <действие>

else

<действие>;

èëè, äëÿ ñîñòàâíûõ îïåðàòîðîâ:

if <условие>

then

begin

 <действие>;

<действие>;

end

else

begin

 <действие>;

<действие>;

end;

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

Оператор case

Оператор case оформляется следующим образом:

case <выражение> of

<множество значений>:

begin

<действия>;

end;

<множество значений>:

<действие>;

<множество значений>:

<действие>;

else

<действие>;

end;

Класс формы

Каждый класс формы определяется в собственном модуле (фактически требование Delphi).

Класс формы должен называться T+Что-то+Form.

Глобальный экземпляр формы (если он есть), по умолчанию определяемый Delphi как глобальная переменная в модуле, где определен класс формы, должна называться Что-то+Form (Это поведение Delphi по умолчанию).

Модуль с определением класса T+Что-то+Form должен называться Что-то+FormU.

Нежелательно определение каких-либо других классов в модуле, где определен класс формы.

Элементам формы должны присваиваться осмысленные названия.

Это обязательно для компонент, на которые имеются ссылки из программного кода, и желательно для всех компонент, включая Label1,2,3 и MenuItem1,2,3.


 

А также другие работы, которые могут Вас заинтересовать

36895. Решение задач с использованием одномерного и думерного массивов 200.5 KB
  Задачи из данного пункта решить двумя способами, используя одномерный массив, а затем двумерный. Размерность массива вводится с клавиатуры.
36896. Спрощена інструкція по роботі з СППР PRIME Decisions 385.5 KB
  для всіх атрибутів які використовуються для прийняття рішень. Введення альтернативних значень для готової цілі та для атрибутів на основі яких здійснюється вибір. Введення альтернатив для головної цілі та для атрибутів в додатковому вікні lterntives 3. Ввести у відповідні стовпці альтернативні значення для атрибутів на основі якого здійснюється вибір.
36897. Адміністрування локальної мережі з використанням FRIENDLY PINGER 1.75 MB
  ІНСТРУКЦІЯ до проведення лабораторної роботи №19 Адміністрування локальної мережі з використанням FRIENDLY PINGER Предмет: Комп’ютерна практика Автор і дата затвердження програми: Новиченко В. Київ Лабораторна робота № 19 Адміністрування локальної мережі з використанням FRIENDLY PINGER 1 Мета роботи Ознайомитись з можливостями програми FRIENDLY PINGER призначеної для адміністрування моніторингу й інвентаризації комп'ютерних мереж. Побудувати топологію локальної мережі згідно з варіантом завдання 2. Сучасні комп’ютерні мережі.
36898. Исследование характеристик усталостной прочности конструкционных материалов при циклических испытаниях 730.5 KB
  Цель работы: Ознакомиться с проблемой усталости авиационных конструкций; параметрами характеризующими цикл нагружения; существующими разновидностями цикла напряжения; характеристиками сопротивления усталости при регулярном напряжении; кривой усталости. ВОПРОСЫ Перечислить основные этапы в гражданской авиации которые связаны с проблемой усталости конструкции самолета. Чем они характеризуются Дать определение...
36899. Ознакомление с работой на учебной микро-ЭВМ 171.73 KB
  Задание 1 Краткое назначение блоков структурной схемы микроЭВМ БП – блок микропроцессора и схем обрамления обеспечивающих его работу формирующий МД МА и сигналы управления микроЭВМ. БУ – блок управления режимами работы МП. БИСМ – блок индикации состояния магистралей. БУКП – блок управления картой памяти.
36900. Изучение принципа работы ОЗУ 356.65 KB
  Изучение принципа работы ОЗУ Цель работы: исследование принципа работы ОЗУ и мультиплексного способа организации общей шины. Задание 1 УГО ОЗУ в соответствии с рисунком 1 А0А3 – адресные входы; CS – выбор микросхемы; W R – запись считывание; DIO1DIO8 – совмещенные информационные вводывыводы Рисунок 1 Задание 2 Провести очистку ячеек памяти ОЗУ по адресам 0 1 2 3 4 D E F Задание 3 Записать 10 8 по адресам 6 11 считать записанную информацию Задание 4 Составить алгоритм работы ОЗУ Алгоритм работы ОЗУ в соответствии с рисунком 2...
36901. КОНТРОЛЬ РАЗМЕРОВ ЦИЛИНДРИЧЕСКИХ ДЕТАЛЕЙ 353 KB
  Цель работы приобрести первичные практические навыки в выполнении измерений с помощью различных универсальных измерительных средств приобрести навыки в оценке годности детали по линейным размерам I. С помощью выбранных универсальных измерительных средств определить действительные размеры проверяемой детали результаты занести в столбцы 712 таблицы 1 и дать заключение о ее годности. Варианты заданий Номер Контролируемые параметры детали образцов А1 А2 А3 А4 А5 А6 А7 1 130 4011 30 50 185H9 32h12 34h8 2 130 395h9 30 50 185D10...
36902. Изучение среды и простейших элементов 405.5 KB
  Домашнее задание выполняется по различным вариантам. В данном варианте меняется только цвет фона всей формы и цвет фона окна Text3. Варианты индивидуальных заданий. Разработать Windowsприложение вычисления значения функции у средствами Visul Bsic Вариант №1 у = b^2 c^2 –t^2 Вариант №2 y = bc^3 – c t^2 Вариант №3 y = b^3 c t^2 Вариант №4 y = c3 t c^2 Вариант №5 y = c^2 b t^2 Вариант №6 y = tk^5 c b^3 Вариант №7 y = c^3 t^2 b^5 Вариант №8 y = c^2 t b^2 Вариант №9 y = c^3 t b^2...
36903. Разработка приложений с разветвляющимися алгоритмами 359 KB
  Lbel1 Cption При х = Lbel2 Cption Функция вычисляется по формуле: Lbel3 Cption Получен результат Y = Lbel4 Cption Lbel5 Cption Лабораторная работа 2.Вариант 37 Text1 Text Text2...