Difference between revisions of "Comments"

From Free Pascal wiki
(Added description of identifier hints in Lazarus IDE, and small formatting tweaks)
 
Line 5: Line 5:
 
They are not interpreted by the compiler and ignored when building your program.
 
They are not interpreted by the compiler and ignored when building your program.
  
== block comments ==
+
 
 +
== Block comments ==
 
<div style="float:left; margin: 0 25px 20px 0; padding:50px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;">{</div><div style="float:right; margin: 0 25px 20px 0; padding:50px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;">}</div>Block comments are delimited by the characters <syntaxhighlight lang="pascal" enclose="none">{ }</syntaxhighlight> <br clear=all />
 
<div style="float:left; margin: 0 25px 20px 0; padding:50px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;">{</div><div style="float:right; margin: 0 25px 20px 0; padding:50px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;">}</div>Block comments are delimited by the characters <syntaxhighlight lang="pascal" enclose="none">{ }</syntaxhighlight> <br clear=all />
 
<div style="float:left; margin: 0 20px 10px 0; padding:40px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;"><nowiki> (* </nowiki> </div>
 
<div style="float:left; margin: 0 20px 10px 0; padding:40px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;"><nowiki> (* </nowiki> </div>
Line 24: Line 25:
 
There is a special class of comment, either beginning {{HL|{$}} or {{HL|(*$}}. This indicates the start of a ''[[Compiler directive|compiler directive]]'', a special instruction to the ompiler about the program, but it does not actually generate instructions to be executed.
 
There is a special class of comment, either beginning {{HL|{$}} or {{HL|(*$}}. This indicates the start of a ''[[Compiler directive|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 ==
 
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]].
 
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:
Line 31: Line 33:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== advice for good comments ==
+
 
 +
== 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.
 +
 
 +
[[File:laz-comment-hint.png]]
 +
 
 +
 
 +
== Best practice 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:
 
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.
 
* 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.
Line 38: Line 49:
 
* 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).
 
* 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 ==
+
 
 +
== See also ==
 
* [[Program Structure|program structure]]
 
* [[Program Structure|program structure]]
 
* [[:Category:Compiler directives|category: compiler directives]]
 
* [[:Category:Compiler directives|category: compiler directives]]
 
* [https://www.freepascal.org/docs-html/ref/refse2.html § “Comments” in the “Free Pascal reference guide”]
 
* [https://www.freepascal.org/docs-html/ref/refse2.html § “Comments” in the “Free Pascal reference guide”]

Latest revision as of 13:42, 14 November 2020

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.

laz-comment-hint.png


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).


See also