Comments: what changed
Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.
Title: Comments
| Old | New | Line | |
|---|---|---|---|
| 1 | + | Go to: [[Reserved words]] \| [[Operators]] | |
| 2 | + | ||
| 3 | + | 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. | |
| 4 | + | ||
| 5 | + | ## Block comments | |
| 6 | + | ||
| 7 | + | <div style="float:left; margin: 0 25px 20px 0; padding:50px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;"> | |
| 8 | + | ||
| 9 | + | { | |
| 10 | + | ||
| 11 | + | </div> | |
| 12 | + | ||
| 13 | + | <div style="float:right; margin: 0 25px 20px 0; padding:50px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;"> | |
| 14 | + | ||
| 15 | + | } | |
| 16 | + | ||
| 17 | + | </div> | |
| 18 | + | ||
| 19 | + | Block comments are delimited by the characters `{ }`\ | |
| 20 | + | ||
| 21 | + | <div style="float:left; margin: 0 20px 10px 0; padding:40px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;"> | |
| 22 | + | ||
| 23 | + | (* | |
| 24 | + | ||
| 25 | + | </div> | |
| 26 | + | ||
| 27 | + | <div style="float:right; margin: 0 20px 10px 0; padding:40px; font-size:500%; font-family: Georgia; background-color: #f9f9f9; border: 2px solid #777777;"> | |
| 28 | + | ||
| 29 | + | *) | |
| 30 | + | ||
| 31 | + | </div> | |
| 32 | + | ||
| 33 | + | 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. | |
| 34 | + | ||
| 35 | + | Example: | |
| 36 | + | ||
| 37 | + | ``` pascal | |
| 38 | + | { public declarations } | |
| 39 | + | ``` | |
| 40 | + | ||
| 41 | + | 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. | |
| 42 | + | ||
| 43 | + | There is a special class of comment, either beginning `{$` or `(*$`. 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. | |
| 44 | + | ||
| 45 | + | ## Line comments | |
| 46 | + | ||
| 47 | + | Line comments or inline comments start with comment delimiter [[Slash|//]] and continue until the [[End of Line|end of the line]]. Example: | |
| 48 | + | ||
| 49 | + | ```delphi | |
| 50 | + | // This is a stupid comment | |
| 51 | + | ``` | |
| 52 | + | ||
| 53 | + | ## Comments as declaration hints in Lazarus IDE | |
| 54 | + | ||
| 55 | + | The Lazarus IDE can display tooltip hints when mouseovering identifiers. You can control this in Options \> Editor \> Completion and Hints. | |
| 56 | + | ||
| 57 | + | The hint shows the function or variable definition, but can also include custom descriptive text taken from comment lines directly above the declaration. | |
| 58 | + | ||
| 59 | + | <figure> | |
| 60 | + | <img src="laz-comment-hint.png" title="laz-comment-hint.png" /> | |
| 61 | + | <figcaption>laz-comment-hint.png</figcaption> | |
| 62 | + | </figure> | |
| 63 | + | ||
| 64 | + | ## Best practice for good comments | |
| 65 | + | ||
| 66 | + | Mentioning some general tips for writing “good” comments may not be left out here, too: | |
| 67 | + | ||
| 68 | + | - 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. | |
| 69 | + | - 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. | |
| 70 | + | - 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. | |
| 71 | + | - 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). | |
| 72 | + | ||
| 73 | + | ## See also | |
| 74 | + | ||
| 75 | + | - [[Program Structure|program structure]] | |
| 76 | + | - [category: compiler directives](/wiki-category/Compiler%20directives) | |
| 77 | + | - [§ “Comments” in the “Free Pascal reference guide”](https://www.freepascal.org/docs-html/ref/refse2.html) | |
| 78 | + | ||
| 79 | + | --- | |
| 80 | + | *From the Free Pascal wiki, page "Comments", as it stood on 2022-08-06 after a change by Kai Burghardt, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).* |