4. КОММЕНТАРИИ

4.1. ОБЩИЕ РЕКОМЕНДАЦИИ ПО КОММЕНИРОВАНИЮ ИСХОДНОГО КОДА

Существующие типы комментариев:

• пояснение сложного (изощренного) кода – очень часто при решении определенных задач (особенно критически важных по скорости работы) не удается избежать использования алгоритмов, которые очень сложны для понимания – в данном случае только подробный комментарий позволяет разобраться, как функционирует данный код;
• маркеры – маркеры обычно используются программистами для временных целей, когда нужно отметить отладочные команды или незаконченные фрагменты кода; когда проект завершается, маркеры и, при необходимости, сопутствующий им код, удаляются;
• разделители – в современных проектах размеры исходных файлов могут быть чрезвычайно большими, и для того, чтобы помочь в отделении структурных частей кода также могут использоваться комментарии; обычно в комментариях подобного типа применяются повторяющие символы (-, =, # и др.), чтобы сделать форматирование более наглядным, однако в данном случае не рекомендуется использовать символ "*";
• резюмирующий код комментарий – этот тип комментария поясняет, каким образом работает код и позволяет без вникания в детали реализации понять алгоритм работы; обычно данный комментарий помещается вначале структурного блока кода (модуля/класса/метода/процедуры/функции и т.д.) и его значимость существенно увеличивается одновременно с ростом размеров кода;
• описание использования кода – данный тип комментария предоставляет информацию, каким образом использовать определенные переменные/процедуры/функции и т.д. и обычно помещается перед ними; данный тип комментария может содержать дополнительную информацию относительно особенностей функционирования кода, например, возможные "побочные эффекты"[4].

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

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

4.2. БЛОЧНЫЕ КОММЕНТАРИИ

Язык Delphi поддерживает два типа комментариев: блочные и однострочные. Delphi поддерживает два типа блочных комментариев. Наиболее часто используемый блочный комментарий – это пара фигурных скобок: { }. Команда разработчиков 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... 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 except block ??? } CallMoreCode; // Finalize the process end; *)

4.3. ОДНОСТРОЧНЫЕ КОММЕНТАРИИ

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

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

Пример однострочного строкового комментария:

// Open the table Table1.Open;

Пример комментария в коде:

if (not IsVisible) then Exit; // nothing to do Inc(StrLength); // reserve space for null terminator

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

СОДЕРЖАНИЕ

Copyright © 2004 Вячеслав Колдовский   Специально для Delphi Plus