Comments

Go Up to Delphi’s Object Pascal Style Guide

The Object Pascal language supports two kinds of comments: block and single-line comments. Some general guidelines for comment usage include:

• It is helpful to place comments near the top of the unit to explain its purpose
• It is helpful to place comments before a class declaration
• It is helpful to place comments before some method declarations
• Avoid making obvious comments
• Remember that misleading comments are worse than no comments at all
• Avoid putting any information into comments that is likely to become out of date
• Avoid enclosing comments in boxes drawn with asterisks or other special typography

Note: Again, internal Embarcadero code should have comments written using US-ASCII characters only and no Unicode symbol.

Block Comments

Object Pascal supports two types of block comments. The most commonly used block comment is a pair of curly braces: { }. The alternative, older style is to use parentheses star: (* *), also called starparen comments.

The Delphi team requires the use of curly brace comments, rather than parentheses star comments. The words in your comments should start on the same line as the first curly brace and the closing brace should be on the line of the final text. In other words, don’t put curly braces on a separate line.

A block comment is always used for the copyright/ID comment at the beginning of each source file. The common scenario here is to have a block comment for each following line and a separating line made of asterisks, as shown in this section.

Single-Line Comments

A single-line comment consists of the characters // followed by text. Include a single space between the // and the comment itself. Place single-line comments at the same indentation level as the code that follows it. You can group single-line comments to form a larger comment.

A blank line should always precede a single-line comment or comment group unless it is the first line in a block. If the comment applies to a group of several statements, then the comment or comment group should also be followed by a blank line. However, if it applies only to the next statement (which may be a compound statement), then do not follow it with a blank line.

Single-line comments can also follow the code they reference. These comments sometimes referred to as trailing comments, appear on the same line as the code they describe. They should have at least one space character separating them from the reference code.

XML Documentation Comments

Delphi supports XML Documentation comments (or XMLDoc) introduced with a triple-slash (///) notation, structured using XML tags, and written before the symbol they refer to.

In terms of style, there should be a space between the /// and the actual text or XML tag, and the symbol should be on the line following the end of the comment (there should not be an empty line between the end of the comment and the symbol it refers to).

Here are some examples, the first with a simple comment and the second including the description of each parameter:

/// <summary>
///    The currently executing thread. This is the same as TThread.CurrentThread.
/// </summary>
class property Current: TThread read GetCurrentThread; 

/// <summary>Trigger corresponding expression objects to be re-evaluated</summary>
/// <param name="Sender">Object that should be re-evaluated</param>
/// <param name="PropName">Property that should be re-evaluated</param>
/// <param name="Manager">The bindingManager the expression belongs in.</param>
class procedure Notify(Sender: TObject; PropName: string = ; 
  Manager: TBindingManager = nil);

Next

Statements