Comments

From Free Pascal wiki

Deutsch (de) English (en) suomi (fi) français (fr) italiano (it) русский (ru)

Comments are human-readable notes or other kinds of annotations to support understanding of code. They are not interpreted by the compiler and ignored when building your program.

block comments

Block comments are delimited by the characters { } or by the bigrams (* *). The latter is a relict from times where computer keyboards did not necessarily have curly braces. It is not wrong to use the bigrams, but they are at large superseded by the use of curly braces.

Example:

{ public declarations }

In Pascal block comments can be nested. However, nested block comment delimiters have to match: If a block comment starts with an opening curly brace, it can not be closed by asterisk-closing-parenthesis but has to be closed by another closing curly brace.

line comments

Line comments or inline comments start with comment delimiter // and continue until the end of the line. Example:

// This is a stupid comment

advice for good comments

Mentioning some general tips for writing “good” comments may not be left out here, too:

  • Write why something is done. Do not write what is done, since that can (provided meaningful identifiers are in place) be determined from the code itself. It would be redundant to repeat what the code already says by itself.
  • Structure your comments. For example write a summary above each method definition explaining what it does and how to use it, i.e. what impact parameters have on the method's behavior.
  • Especially name (non-trivial) constraints that came from other places, that made you choose writing a particular line of code, or select a particular approach to solve the problem.
  • Write in one language throughout the whole project. De facto English is the most prevalent comment language, but especially in the context of teaching other languages are more suitable. It is important that all team members can express complex circumstances in the used language (that's easier said than done).

see also