Стандарт стилевого оформления исходного кода DELPHI. XML комментарии и генерация документации в Delphi

Страница 5 из 9

Комментарии

Язык 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... 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. }

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

Правильно

Второй тип блочного комментария содержит два символа: скобку и звездочку: (* *) . Этот тип комментария используется при разработке исходного кода. Его преимуществом является то, что он поддерживает вложенные комментарии, правда комментарии должны быть разного типа. Вы можете использовать это свойство для комментирования больших кусков кода, в котором встречаются другие комментарии:

(* 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

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

Язык программирования Delphi достаточно прост для освоения, но очень эффективный и мощный. Самое первое, с чем надо познакомиться - это комментарии.

Комментарии - это любой текст, который абсолютно не влияет на код программы. Он никогда не компилируется и не вставляется в исполняемый файл, а используется только для пояснений кода.

Комментарии могут оформляться двумя способами:

1. все, что идет после двойного слеша // , воспринимается как комментарий
   (так можно оформить только одну строку комментария);
2. все, что заключено в фигурные скобки { и }, тоже является комментарием
   (в этом случае можно включить в комментарий сколько угодно строк).

Пример комментария

// Это комментарий.

Это уже не комментарий

{ Это снова комментарий
И это тоже }

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

Теперь вы готовы к изучению языка программирования Delphi. Создайте новый проект. После этого перейдите в редактор кода. Здесь для вас уже написана заготовка будущей программы.

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

Сгенерированный оболочкой Delphi шаблон

unit Unitl; //Имя модуля

interface

uses //После этого слова идет перечисление подключенных модулей.
Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
Dialogs;

type //После этого идет объявление типов
TForml = class (TForm) //Начало описания нового объекта TForm. Здесь описываются компоненты и события Формы
private //После этого слова можно описывать закрытые данные объекта
{ Private declarations }
доступные только для объекта TForml
public //После этого слова можно описывать открытые данные объекта
{ Public declarations } //Подсказка, которую сгенерировал Delphi. Здесь можно описывать переменные и методы,
доступные из любого другого модуля
end ; //Конец объявления типов

var //Объявление глобальных переменных
Forml: TForml; //Это описана переменная Forml типа объекта TForml

implementation

{$R *.dfm} //Подключение.dfm файла (файл с данными о визуальных объектах)

end . // end с точкой - конец модуля

Если что-то осталось еще непонятным, то в процессе создания реальных программ все встанет на свои места. Не старайтесь запомнить все сразу, потому что это нереально. Слишком много новой информации, не подкрепленной практикой. Старайтесь понять только смысл написанной программы.

Практически все строчки заканчиваются знаком "; " (точка с запятой). Этот знак показывает конец оператора. Он ставится только после операторов и никогда не используется после ключевых слов типа

uses, type, begin, implementation, private, public

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

Итак, разберем структуру кода. В самом начале стоит имя модуля. Оно может быть любым, но таким же, как и имя файла (без учета его расширения). Изменять имя модуля вручную нежелательно. Если все же надо изменить, то сохраните сначала модуль со старым именем. Для этого нужно выбрать команду меню: File | Save As (Файл | Сохранить как).

Желательно давать модулям понятные имена. В этом случае по имени можно определить, что находится внутри одноименного модуля. Трудно догадаться, что находится в файле под именем Unitl.pas. Файлам также желательно давать такие имена, которые связаны с их содержимым. Например, главную форму программы лучше сохранять в файле с именем MainUnit.pas или MainModule.pas. В этом случае модуль и файл будут иметь имя MainUnit или MainModule, и вы можете сразу определить, что это главная форма.

Далее идет подключение глобальных модулей. Все процедуры, функции, константы описаны в каком-нибудь модуле, и прежде чем эти процедуры использовать, нужно его подключить. Вы можете знать о существовании какой-нибудь функции. Но чтобы об этом узнал компилятор, вы должны указать модуль, где описана эта функция, понятным для компилятора языком. Например, вам надо превратить число в строку. Для этого в Delphi уже есть функция IntTostr. Она описана в модуле Sysutils. Если вы хотите воспользоваться этой функцией, вам надо подключить этот модуль к своему модулю Формы (напечатать название Sysutils в разделе uses).

Существуют четыре типа разделов:

1. Private - свойства и методы из этого раздела доступны только этому объекту. Другие объекты не могут вызывать эти методы и читать/записывать свойства;
2. Protected - эти свойства и методы доступны только этому объекту и потомкам (объектам, которые происходят от нашего и наследуют его свойства). Сторонние объекты не могут получить доступ к хранящимся здесь свойствам и методам;
3. Public - все, что описано здесь, доступно всем;
4. Published - когда будут писываться собственные компоненты приложения, в этом разделе мы будем описывать свойства и события, которые должны быть отображены в объектном инспекторе. Эти свойства доступны всем.

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

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

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

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

var //Объявление глобальных переменных
Forml: TForml; //Это описана переменная Forml типа объекта TForml

В этом примере объявлена переменная Forml типа объекта TForml. Когда будет создан объект TForml, то его указатель будет записан в переменную Form1. Данная переменная глобальная и существует, пока программа выполняется, а значит, к ней всегда можно получить доступ.

Ключевое слово implementation тоже пока трогать не будем, а оставим на будущее, когда наши знания о Delphi немного расширятся. Последнее, что осталось рассмотреть в этой главе, - ключ {$R * dfm}.

В фигурных скобках могут быть не только комментарии, но и ключи для компилятора. Они отличаются тем, что выглядят как {$Буква Параметр]. Буква - указывает на тип ключа. В нашем случае используется буква R . Этот ключ указывает на то, что надо подключить файл ресурсов, в данном случае .dfm файл (файл с данными о визуальных объектах) с тем же именем, что и имя модуля. Если имя модуля Mainunit , то нужно изменить этот ключ на {$R MainUnit .dfm}. Ключ R - это единственный ключ, который пока понадобится.

Любой программный код в Delphi заключается между begin и end. Ключевое слово begin означает начало кода, a end - конец. Например, когда вы пишете процедуру, то сначала нужно написать ее имя (как это делать, мы поговорим позже), а потом заключить ее код между операторными скобками begin и end.

По материалам сайта

Страница 7 из 12

Классы

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

Тело класса при его декларации подчинено следующей структуре:

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

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

Уровни доступа

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

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

Таким образом, в Object Pascal существует четыре уровня доступа для членов класса: published, public, protected и private - в порядке уменьшения видимости. По умолчанию, уровень доступа - published. В общем, члены класса должны давать наименьший уровень доступа, который подходит для этого члена. Например, член, к которому имеют доступ классы из одного модуля должен иметь уровень доступа private. Кроме того, объявляя члены класса с наименьшим уровнем доступа, Вы позволяете компилятору воспользоваться дополнительными возможностями для оптимизации. С другой стороны, если Вы планируете в дальнейшем порождать дочерние классы от Вашего класса, то нужно использовать уровень доступа protected.

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

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

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

Объявление методов

По возможности, объявление метода должно располагаться на одной строке:
Например:
procedure ImageUpdate(Image img, infoflags: Integer,
x: Integer, y: Integer, w: Integer, h: Integer)