1. Computing
Commenting Delphi code
Learn the art of helping yourself, when it comes to code maintenance. The purpose of adding comments to Delphi code is to provide more program readability using understandable description of what your code is doing.
 More of this Feature

Printer friendly versionPrinter friendly version
 Join the Discussion
"Post your views and comments to this chapter of the free Delphi Programming Course"
Discuss!
 Related Resources
• A Beginner's Guide to Delphi Programming.TOC

• Delphi Coding Standards and Conventions

Welcome to the eighth chapter of the FREE online programming course:
A Beginner’s Guide to Delphi Programming.
Learn the art of helping yourself, when it comes to code maintenance. The purpose of adding comments to Delphi code is to provide more program readability using understandable description of what your code is doing    

Why, How and When
Even though at *this* stage of your latest Delphi project development you are pretty sure about what every line in the source does, you should know that after a few months even the *simplest* functions will be hard to read - you'll simply forget what the idea was.

Commenting code is a manner of adding (displaying) textual information in relation to your code without it being parsed by compiler (or compiled in an exe).
The purpose of adding comments to code is to provide an understandable description of what your code is doing - to make your source more readable - for you and for other developers that may need to alter (or understand) the code. When you come back to maintain the code a year later, you will thank yourself. Other users who attempt to maintain your code will thank you as well.

There are two kinds of comments in Delphi: block comments and line comments.

Line comments (the // symbol - double-slash) were added within Delphi source, as the name suggests, only comments out the current line. They are put at the start of the bit of code you want to comment out and stop the compiler *seeing* any of the code after the comment symbol and until the end of the line.
In the next example the j:=5 part of the code is commented.

var i,j :integer
...
i:=0;  //j:=5
...

There are two ways to add block comments. The { } symbols and (* *) are used (in pair) to comment out a block of code (i.e. more than one line). That is, any text between a left brace and a right brace constitutes a comment; text between a left-parenthesis-plus-asterisk and an asterisk-plus-right-parenthesis also constitutes a comment. For example (from Windows.pas):

 {The name immediately following SUBLANG_ 
 dictates which primary language ID that 
 sublanguage ID can be combined with to 
 form a valid language ID.}

  SUBLANG_NEUTRAL  = $00; { language neutral }
  {$EXTERNALSYM SUBLANG_NEUTRAL}
  SUBLANG_DEFAULT  = $01; { user default }
	...

Notice, however, that a text that contains a dollar sign ($) immediately after the opening { or (* (for block comments) is a compiler directive - something definitively not ignored by the compiler. For example, {$WARNINGS OFF} tells the compiler not to generate warning messages.

Note one more thing, if you start a comment with an open brace "{", Delphi expects the comment to end with a closing brace "}", and not an asterisk-paren "*)".

You must be quite careful when using block comments as it often seems the case that you could want to comment out a chunk of code that already has comments in it. However, the problem with this is that we can't nest comments (i.e. have one set of comments inside another) in Delphi Pascal. But, if you have a large amount of code that you want to comment out, none of the above operators may help, depending on whether you have already used those operators in the code. Here's a definitive way to comment out code:

{$IFDEF False}

 your code goes here
 do not fear if you have used
 line or block comment inside
 this block!

{$ENDIF}

As a help to developer, Delphi code editor (by default) uses italics and a blue font to specify that a peace of code is actually a comment.

   

Delphi Commenting TIPS
  • Delphi Pascal doesn't support nesting comments of the same type within each other.
  • Each unit should begin with a comment block, that generally describes the contents of the unit.
  • Each class definition and each method (procedure/function) within a unit should have a separate function comment, above the method. In certain circumstances, you will use comments to document the arguments passed to a procedure, to state whether those arguments should be within a certain range of values, to convey whether global variables are changed within the procedure, and to relate the procedure's return values.
  • Avoid making obvious comments: i := i + 1; // Add one to i
  • Misleading comments are worse than no comments at all.
  • For commenting, usually { } pairs shall be used.
  • The alternative notation of (* *) shall be reserved for temporarily removing code ("commenting out") during development.
  • The use of // shall be restricted to one-line comments.
  • Tricky, confusing, and/or clever coding techniques should always be documented (if not avoided entirely).
  • Comments preceding functional blocks of code should be aligned with the code on the left hand side
  • When documenting source code, don't forget to update existing comments if the code change causes the description to be inaccurate. Always make sure the description still describes the new functionality.
  • If your comments speak to how the code works, instead of to what it does, you have created an additional code-maintenance problem, because comments that describe how code works must be revised whenever you change the code.
  • Always enter or revise your comments as soon as you write the code. Avoid "saving it for later," because there is rarely time to do it later, or, if there is, you will not understand the code as well when you come back to it.

   To the next chapter: A Beginner's Guide to Delphi Programming
This is the end of the eighth chapter, in the next chapter, we'll deal with "cleaning your Delphi code errors".

If you need any kind of help at this point, please post to the Delphi Programming Forum where all the questions are answered and beginners are treated as experts.

A Beginner's Guide to Delphi Programming: Next Chapter >>
>> Cleaning your Delphi code errors

©2014 About.com. All rights reserved.