Comment (programming)
Comments are annotations within programming languages and text description languages . All these languages consist of instructions for the computer (code) and notes for text editors (comments). Comments are used to make the source text easier to understand for people. If the source text is processed further ( compiled , interpreted , parsed, etc.), comments are ignored by the processing software and therefore have no influence on the result. The user or viewer of the result can therefore no longer infer the existence of the comments.
Occasionally, however, comments are also used to store machine-readable meta information or to supplement a language (see #Use contrary to definition ).
General syntax
For a language, it is specified where a comment begins and where it ends. A general distinction is made between block and line comments. Line comments automatically end at the end of the line. Block comments can extend over several lines and end after the introduction with the end character. In some languages, block comments are also allowed within a single code command. However, this is rarely used.
The content of a comment and thus its use can be freely selected by the editor and is not subject to any binding syntax, except that in the case of block comments, the comment end marker must not be included in the comment itself. As a rule, comments are recorded in “human” language, either in the author's native language or in a common language. Comments are usually just text (i.e. no formatting, graphics, sounds, etc.), as most languages only allow such comments.
use
Despite their free usability, comments are often used in the following ways:
- Information about the entire source code
- At the beginning of a source text, the author can add preliminary remarks to the same, including details of the author, the license, the creation date, contact address for questions, a list of other required files, and a greeting to programming colleagues.
- Structure of the source text
- Headings and sections can be marked as such. Often not only linguistic means are used ("This is where the resident part begins"), but also graphic means that can be implemented through text ("**** = - resident part - = ****")
- Explanation of a single line
- In this way, the mode of operation or the meaning of a text part (e.g. program line, tag) can be explained so that others or the author himself can understand it more easily later.
- Indication of work to be done
- Comments can indicate insufficient pieces of code ("The support for umlauts has to be improved here") or they can be placeholders for completely missing pieces of code ("Insert table display here").
- Comment out
- If a component of the code is to be temporarily made ineffective, it is "commented out", i. i.e. it is converted into a comment. From the perspective of the compiler or interpreter, this part of the source text is no longer code, which is equivalent to deletion. However, it is retained as a comment and can later be converted back into regular code.
Use contrary to definition
Exceptions to the above definition of comments (comments that are not always ignored by the computer) include:
- Preprocessor
- Languages that do not have their own syntax for preprocessor statements use special comments. In the first pass, the preprocessor determines the necessary information from the comments; in the second pass (compiling, interpreting, etc.) these comments are then skipped (like all comments).
- Embedding of foreign languages
- In source texts made up of several languages, one language is embedded in the comments of the other. Probably the best-known example are JavaScript instructions that are hidden in HTML comments. This is mostly just a temporary solution to stay compatible with older programs that would not understand the embedded language and would therefore consider them to be errors.
- Automated code generation
- If code is created with a development environment (e.g. HTML editor), this information can be stored in comments that are relevant to you, but which are of no use to those who process the code (e.g. browser).
- Automated source code documentation
- There are auxiliary programs for some programming languages that can extract special comments from the source code and automatically generate software documentation by analyzing the actual program code. Tools for this are for example Sphinx , Javadoc or Doxygen .
- Code generation
- Special comments make it possible to store instructions for various tools in the source code. An example of this is XDoclet . So-called annotations are processed in a separate processing run and other files are generated from the source text in addition to the actual program.
- Conditional Comments
- Special method for executing (X) HTML / CSS code in Internet Explorer . Commands that are only to be executed in certain Internet Explorer versions are written within comment tags. Typically, this method is used to load style sheets that correct certain bugs in older versions of IE. The method is only supported to a limited extent from IE version 10.
- Compiler instructions
- Some languages that do not have their own syntax for compiler instructions use comments to give special instructions to the compiler . For example: In Pascal , comments whose first character is a $ are interpreted as a compiler directive.
Syntax using the example of some programming and markup languages
The syntax of comments is different in different languages. Here are some examples, the word code is used as a placeholder for any executable program code and is intended to make it clear that in some cases it is not necessary to start a new line for a comment or the continuation of the source text :
| language | variant | syntax |
|---|---|---|
| Fortran | Line comment |
C a comment up to the end of the line * a comment up to the end of the line Code ! You can also start a comment in the middle of a line |
| C , C ++ , C # , D , JavaScript , PHP , Java , CSS , SQL | Block comment |
Code / * A comment that may also contain line breaks . * / Code |
|
C , C ++ , C # , D , JavaScript , PHP , Java |
Block comment | $ x = 5 * (2 + / * a comment within an instruction * / 3); |
| D. | Block comment (nested) |
Code / + A comment / + which may also contain sub- comments + / . + / Code |
| Pascal , Modula-2 , Oberon , Seed7 , AppleScript | Block comment |
Code (* a comment, with line breaks *) Code |
| Pascal | Block comment |
Code {a comment, with line breaks} code |
| AutoIt | Block comment |
Code #cs A comment, with line breaks #ce code |
| C , C ++ , C # , Pascal , Object Pascal , JavaScript , PHP , Java , Bourne-Shell , PowerFlex , Scilab | Line comment |
Code // Comment that goes to the end of the line // If it should go on, the line must end with a \ backslash |
| Shell script , Perl , Python , R , Ruby , PHP (rarely), Windows PowerShell , Seed7 , Tcl | Line comment | Code # a comment to the end of the line |
| Assembler , Lisp , INI file , AutoIt , zone file | Line comment | Code ; Comment to the end of the line |
| BASIC , batch (cmd.exe, ...) | Line comment | REM comment to the end of the line |
| BASIC , Visual Basic | Line comment | Code 'Comment to the end of the line |
| SGML (HTML1 to HTML4) | Block comment | Outside of tags and declarations only: <!-- Kommentartext -->
Multiple comments are allowed |
| SGML (HTML1 to HTML4) | Block comment | Only within tags and declarations: -- Kommentartext --
|
| XML (e.g. XHTML ), HTML | Block comment | Outside of tags and declarations only: <!-- Kommentartext -->
|
| Ada , AppleScript , SQL , Haskell , VHDL , Lua | Line comment | Code - a comment to the end of the line |
| Erlang , LaTeX , Matlab , PostScript , TeX | Line comment | Code % a comment to the end of the line |
| Matlab | Block comment (from version 7.x) |
Code % { A comment that may also contain line breaks . %} Code |
| ABAP | Line comment | Code "a comment to the end of the line |
|
Code * a comment up to the end of the line * a comment up to the end of the line code |
||
| M4 | Line comment | Code dnl a comment to the end of the line |
| Latex | Block comment (only with additional packages like "verbatim" or "comment") |
Code \ begin {comment} A comment, with line breaks \ end {comment} code |
| Mathematica | Block comment |
Code (* A comment that may also contain line breaks . *) Code |
| Vimscript | Line comment | Code "a comment to the end of the line |
| Lisp | Line comment |
Code ;; a comment to the end of the line ; Some LISP dialects require two and some require one; |
| Haskell | Block comment (nested) |
Code {- A comment, with line breaks and a nested comment: {- I am the inner comment and only I am closed by the following character combination: -} , which is closed by the following character combination: -} Code } |
The esoteric programming languages brainfuck and INTERCAL (the latter in connection with the compiler "ick") offer an interesting possibility to use comments : Everything that is not a valid command is ignored by the interpreter or compiler. Comments don't have to be specially marked.