Главная III Курс Визуальное программирование Требования к содержанию и оформлению отчетов по лабораторным работам
Требования к содержанию и оформлению отчетов по лабораторным работам
10.03.2012 16:29

Цель

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

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

Рассматриваются файлы, содержащие исходный код на языке 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.

Похожие статьи:
Обновлено 10.03.2012 16:34
Поделиться с друзьями:
Комментарии:

Дисциплины