A comment in a programming language or a text mark-up language (such as HTML) is a piece of text that is—in principle—ignored by the program processing the instructions (for example a compiler or interpreter), therefore the program should behave identically to if the comment did not exist.
Comments are used for several different purposes:
- To explain the algorithm or flow of the program to other programmers reading the code.
- To provide copyright, authorship, or other information about the program.
- To hold information that can be read and processed by the compiler or programming tools. Since comments are, by definition, ignored by the compiler, some programmers consider such non-ignored "comments" as "a hack" that is, by definition, source code and not merely a comment.[Citation Needed] This can include the following:
- Compiler switches, such as telling the compiler to include a block of code if particular options are set.
- Entries for a "to do" list, which can be read by a tool compiling such a list.
- Formal program documentation, which can be extracted to a separate help file or manual.
- To disable sections of code, useful when trying to discover problems.
Some people believe that comments are most commonly used for documenting how a program or individual algorithm works for future reference. While that may be true in machine language, many programmers feel that well-written source code in a high-level language can use descriptive variable names and function names to indicate what is done and how it is done -- and so requires fewer comments, and in some cases no commments.
Some of the information held in comments include:
"Who wrote the first version of file?", "Who else has edited this file?", "Who owns this file?", "How do I contact those people -- phone number, email address, etc.?", "What other features did the author want to add to this file but didn't because he ran out of time?", "When was this file originally written?", "When was this file last updated?", "Why did the author write this?", "Have any other ways of implementing this function been tried, and if so, why were they rejected?", "What program was used to create/edit this document?", "Where is the master version of this file, not merely my local copy?", "Is this file a confidential trade secret, public domain, or something in-between?", "When is this file expected to become obsolete?", etc.
Automatic computer-language translation tools (C to assembly language; Fortran to C, etc.) typically produce files with many comments, often beginning with "DO NOT EDIT. This file is machine-generated", the name of the original source file that should be changed instead, the exact command to the translation tool that generates this file, etc.
Types of comments
Comments come in two main forms: single-line comments, and block comments.
Comments start with a particular character or sequence of characters, which vary depending on the computer language.
Single-line comments finish at the end of the line the start sequence is in. Multiple-line comments finish with another particular character or sequence of characters, which may or may not be on the same line.
Comments in different languages
The following table lists different syntaxes for comments in different programming and mark-up languages.
|Computer language||Single-line start sequence||Multi-line start sequence||Multi-line end sequence|
|BASIC, Visual Basic|| REM
|Mark-up language||Single-line start sequence||Multi-line start sequence||Multi-line end sequence|
Normally, multiple-line comments cannot be nested. That is, one comment cannot enclose another comment. However, a comment of one type can be used to enclose another comment.
The only normal reason for nesting comments is when disabling sections of code that itself already has comments. Some examples follow. In these examples, the original comment is highlighted in beige, and the disabled code is in aqua.
- This BASIC example shows that single-line comments can include other single-line comments:
- ' a=b*2+c 'Not sure about the maths here.
- This Java example has a multi-line comment surrounding a single-line comment:
- As Pascal has two different multi-line comments, one can surround the other:
Formal Documentation in Comments
When comments are styled in a formal way they can be read autonomously by a program for the purposes of automatically generating documentation. The following is an example of a Doxygen comment documenting a function in C++:
/** * @brief Exit the program. * @author Joe Bloggs <firstname.lastname@example.org> * @param status Status value which should be 0 if everything went well. * @return an error code (will never return if successful). */ int exit(int status);