Difference between revisions of "Comments"
From Free Pascal wiki
Jump to navigationJump to searchm |
(review) |
||
| Line 1: | Line 1: | ||
| − | |||
{{Comments}} | {{Comments}} | ||
| − | Comments are human-readable notes or other kinds of annotations | + | 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 delimited by | + | == block comments == |
| − | + | Block comments are delimited by the characters <syntaxhighlight lang="pascal" enclose="none">{ }</syntaxhighlight> or by the bigrams <syntaxhighlight lang="pascal" enclose="none">(* *)</syntaxhighlight>. | |
| − | + | 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: | Example: | ||
| − | + | <syntaxhighlight lang="pascal"> | |
| − | <syntaxhighlight> | + | { public declarations } |
| − | |||
</syntaxhighlight> | </syntaxhighlight> | ||
| − | + | 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 [[Slash#comment|<syntaxhighlight lang="pascal" enclose="none">//</syntaxhighlight>]] and continue until the [[End of Line|end of the line]]. | ||
Example: | Example: | ||
| − | |||
<syntaxhighlight> | <syntaxhighlight> | ||
| − | + | // This is a stupid comment | |
</syntaxhighlight> | </syntaxhighlight> | ||
| − | == | + | == advice for good comments == |
| − | * [[ | + | Mentioning some general tips for writing “good”<!-- it's up for debate what constitutes a good comment --> 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 == | ||
| + | * [[Program Structure|program structure]] | ||
| + | * [[:Category:Compiler directives|category: compiler directives]] | ||
| + | * [https://www.freepascal.org/docs-html/ref/refse2.html § “Comments” in the “Free Pascal | ||
| + | reference guide”] | ||
Revision as of 10:50, 1 May 2018
│
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 commentadvice 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
- program structure
- category: compiler directives
- [https://www.freepascal.org/docs-html/ref/refse2.html § “Comments” in the “Free Pascal
reference guide”]
