Требования к содержанию и оформлению отчетов по лабораторным работам |
10.03.2012 16:29 | |
ЦельПовысить читаемость исходного кода, разрабатываемого программистами. Сфера приложения и определенияРассматриваются файлы, содержащие исходный код на языке Object Pascal, то есть файлы проекта и файлы модулей. Даются рекомендации по оформлению исходного кода и именованию типов, переменных, процедур и функций, в том числе классов, их свойств и методов. Под объектом далее будем понимать не объект в смысле Object Pascal, а любую сущность языка – тип, переменную, модуль, процедуру – имеющую собственный идентификатор. Заметим, что идентификаторы разных объектов в общем случае не обязаны быть различными. Общие требованияЕсли строка исходного кода не умещается по ширине в 80 символов, то ее необходимо перенести на следующую строку. В исходных файлах не следует использовать табуляцию. Все ключевые слова пишутся в нижнем регистре. Например if, while, platform, string, deprecated. Пустые строки могут повысить читабельность путем группирования секций кода, которые логически связаны между собой. Язык Object Pascal является очень легким для понимания языком, поэтому нет особой необходимости в использовании большого количества пробелов. Не следует использовать пробелы:
Все строки должны быть исключены из кода и заменены константами. Несмотря на то, что глобальные переменные разрешены языком 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 поддерживает два типа комментариев: блочные и однострочные. Общие рекомендации по использованию комментариев могут быть следующими:
Однострочный комментарий состоит из символов // со следующим за ними текстом комментария. После символов // должен идти пробел и затем текст. Однострочные комментарии, помещенные на отдельную строку, должны иметь отступы такие же, как и код, в котором они встречаются. Однострочные комментарии можно сгруппировать, чтобы сформировать большой комментарий. Необходимо избегать использовать комментарии в коде для каждой строки модуля. Однострочный комментарий может начинаться с новой строки и может продолжать код, который он комментирует. В этом случае между кодом и комментарием должен быть хотя бы один пробел. Если больше одного комментария следует за кодом, то они должны быть выровнены по одному столбцу.
Файлы исходного кодаОперационная система поддерживает длинные имена файлов. Исторически, некоторые исходные файлы 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 для данных. Данные должны быть объявлены в приватной секции и доступ к ним должен осуществляться с помощью методов или свойств. Внутри области видимости члены класса следует располагать в следующем порядке:
Именование методовВ имени метода всегда должна содержаться команда к действию или глагольная фраза. Методы для установки и получения значений свойств должны именоваться по правилу: для получения - Get+ИмяСвойства; для установки - Set+ ИмяСвойства. Методы для проверки булевских свойств класса должны именоваться по правилу Is+ИмяСвойства.
Определение функций, процедур и методовНикогда не разрывайте строку между параметром и его типом, кроме параметров, перечисляемых через запятую. Двоеточие для всех объявлений переменных не должно содержать перед собой пробелов и иметь один пробел после перед именем типа. По возможности, объявление должно располагаться на одной строке.
Объявление параметровКогда объявляется список параметров для процедуры, функции или метода пользуйтесь следующими рекомендациями:
Локальные процедурыЛокальные функции и процедуры должны иметь стандартный отступ в два пробела вправо от их владельца и сама процедура должна выделяться пустыми строками по одной перед и после локальной процедуры. Если "внешняя" процедура имеет локальные переменные, то они должны декларироваться перед локальной процедурой, независимо от того, будет ли в локальной процедуре осуществляться доступ к ним или нет. Однако общие соображения таковы, что локальных процедур следует избегать.
ОператорыНе допускается объединение нескольких операторов на одной строке. Операторные скобки 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 |