Comments
│
Deutsch (de) │
English (en) │
suomi (fi) │
français (fr) │
italiano (it) │
русский (ru) │
Go to: Reserved words | Operators
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. There is one place where the (* and *) bigrams can be useful. if you are testing code and want to "dike out" or disable certain sections by marking them as inoperative, the pieces can be surrounded by these bigrams, and it will not matter if there are { and } comments inside of them.
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.
There is a special class of comment, either beginning {$ or (*$. This indicates the start of a compiler directive, a special instruction to the ompiler about the program, but it does not actually generate instructions to be executed.
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
Comments as declaration hints in Lazarus IDE
The Lazarus IDE can display tooltip hints when mouseovering identifiers. You can control this in Options > Editor > Completion and Hints.
The hint shows the function or variable definition, but can also include custom descriptive text taken from comment lines directly above the declaration.
Best practice 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).
