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

Комментарии

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

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

Блочные комментарии

Object Pascal поддерживает два типа блочных комментариев. Наиболее часто используемый блочный комментарий - это пара фигурных скобок: { }. Команда разработчиков Delphi предпочитает использовать этот комментарий как можно проще и как запасной. Используйте в таких комментариях пробелы для форматирования текста и не используйте символы зведочка "*". При переносе строк необходимо сохранять отступы и выравнивание

{ 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... etc... 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. }

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

{ TMyObject.MyMethod This routine allows you to execute code. } procedure TMyObject.MyMethod; begin end;

procedure TMyObject.MyMethod; {****************************************************** TMyObject.MyMethod This routine allows you to execute code. *******************************************************} begin end;

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

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