Comment
|
|
Template:Wiktionary In computer programming, comments are a part of the source code which, together with its layout, is used to explain the code. Such comments are generally ignored by compilers and interpreters. Comments also exist in many markup languages and hardware description languages.
| Contents |
Usage
Comments could summarise code or explain the programmer's intent. This is called the why rather than how approach. The two are often close, but not always. According to this school of thought, restating the code in plain English may be a waste of time; the need to explain the code may be a sign that it is too complex and should be rewritten.
- "Don't document bad code – rewrite it" (The Elements of Programming Style, Kernighan & Plauger).
- "Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do." (Code Complete, McConnell)
Comments could also be used to guide a new programmer through source code that performs some task. In this case almost every line could be commented. New programmers can gain much insight in various branches of programming and computer science by reading through extensively commented source code. Typical things that could be commented on are function calls and arguments, algorithms used, and caveats.
Sometimes a programmer thinks up a neat trick to perform a certain task. Comments could in this case provide an explanation of the trick used. Although the why rather than how approach discourages such comments, sometimes an explanation is just what is needed to make a future programmer understand what a certain piece of source code is doing. This might especially be true in the case of rarely-used optimizations, constructs or function-calls. For example, a programmer may add a comment to explain why an insertion sort was chosen instead of a quicksort, as the former is, in theory, slower than the latter. This could be written as follows:
list = [f (b), f (b), f (c), f (d), f (a), ...]; // Need a stable sort. Besides, the performance really does not matter. insertion_sort (list);
Logos, diagrams, and flowcharts consisting of ASCII art constructions can be inserted into source code formatted as a comment. Additionally, copyright notices can be embedded within source code as comments.
In debugging, programmers will sometimes mark a code fragment as a comment, such that the program will not compile or interpret it. This is called commenting out the fragment.
Styles
Comment styles are often agreed upon before a project starts. Usually programmers prefer styles that are easy to modify and difficult to break.
For example, C-style comments could look like this:
/*
This is the comment body.
*/
Or maybe like this:
/***************************\ * * * This is the comment body. * * * \***************************/
If a programmer's editor doesn't manage the second variant automatically, it may discourage changes to the comments, thus leading to comments which are out of date with respect to the code. On the other hand, the visibility of the second comment variant is much higher.
Some people, such as Allen Holub (in his book Enough Rope to Shoot Yourself in the Foot, ISBN 0-07-029689-8, 1995, McGraw-Hill), advocate aligning the left edges of comments:
/* This is the style recommended by Holub for C and C++. * It is demonstrated in Enough Rope, in rule 29. */
/* This is another way to do it, also in C. ** It is easier to do in editors that do not automatically indent the second ** through last lines of the comment one space from the first. ** It is also used in Holub's book, in rule 31. */
Different styles can be chosen for different areas of code, from individual lines to paragraphs, routines, files, and programs. If the syntax supports both comments that end at the end of a line and comments that end when some sequence of characters are encountered, it might be an idea to use the end-of-line style only for minor comments (declarations, blocks and edits).
Certain projects try to define rules like "one comment every ten lines". They can be counterproductive when adhered to with too much rigor, but might still be of use when one wants to quickly judge after writing a body of code whether one needs to check if enough comments are in place.
Automatic documentation generation
Some programming tools can read structured information in comments in order to generate documentation automatically. Examples include the javadoc program, designed to be used with the Java programming language, and doxygen, to be used with C++, C, Java, IDL and others.
C# implements a similar feature called "XML Comments" which are read by IntelliSense from the compiled .NET assembly. The next revision of Visual Basic will also feature this.
Other uses
Developer tools might store "meta" data in comments, such as insert positions for automatic header file inclusion, commands to set the file's syntax highlighting mode, or the file's revision number.
Examples
Summary
(the word "comment" is used here, as an example of a comment):
- Algol:
comment comment;
- AppleScript:
(*comment*)--comment
- BASIC (various dialects):
'comment(not all dialects)REM comment
- Brainfuck and Brainfork:
comment(comment must not include the characters< > + - , . [ ])
- C (K&R, ANSI/C89/C90), CSS, TSQL, and PL/I:
/* comment */
- C (C99), C++, JavaScript and Java:
/* comment */// comment
- D:
/* comment */// comment/+ comment +/
- Delphi (Object Pascal):
(* comment *){ comment }// comment
- DCL:
$! comment
- Fortran:
C comment(exactly 6 columns betweenCcharacter and comment)
- Fortran 90:
! comment
- Lisp and Scheme
; comment
- Pascal, Modula-2, Modula-3, Oberon, and ML:
(* comment *)
- Perl, Python, Ruby, C shell, Bourne shell, Tcl, and AWK:
# comment
- PHP:
# comment// comment/* comment */
- PILOT:
R:comment
- REALbasic:
' comment// commentrem comment
- SGML, including HTML, and MediaWiki
- A comment declaration starts with
<!, followed by zero or more comments, followed by>. A comment starts and ends with--, and does not contain any occurrence of--. Valid examples are:
<!-- comment -- -- comment -->,<!------ comment -->, or<!>.
- A comment declaration starts with
- TeX, LaTeX, PostScript:
% comment
- Texinfo:
@c comment@comment comment
- VHDL, TSQL:
-- comment
- Visual Basic:
'commentRem comment
- XML, including XHTML
<!--comment-->(comment must not contain--or start or end with-)
If there are two markers delimiting the word comment, then they should be included at the beginning and end of the comment. If there is one, it begins at the start of the comment character(s) and ends at the end of the line. An exception to this is PILOT, where a new "command letter" may begin right after a comment, on the same line. Also note that line continuation may apply.
In-context
C
/*
* Check if we are over our maximum process limit, but be sure to
* exclude root. This is needed to make it possible for login and
* friends to set the per-user process limit to something lower
* than the amount of processes root is running. -- Rik
*/
if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
&& !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
goto bad_fork_free;
(This is from the fork.c file from the Linux kernel source)
Java
/**
* Registers the text to display in a tool tip. The text
* displays when the cursor lingers over the component.
*
* @param text the string to display. If the text is null,
* the tool tip is turned off for this component.
*/
public void setToolTipText(String text) {
(from the Sun Microsystems javadoc documentation; the comment is designed to be read by the javadoc processor)
Perl
# a strange way to check whether any significant editing
# have been done: check whether any new non-empty lines
# have been added. Yes, the below code ignores *any* space
# in *any* line.
while (<REP>) {
s/\s+//g;
$unseen++ if $_ ne '' and not exists $REP{$_};
}
(from perlbug.PL in the standard perl distribution)
PHP
/*
* Scan forwards to find beginning of another run of changes.
* Also keep track of the corresponding point in the other file.
*
* Throughout this code, $i and $j are adjusted together so that
* the first $i elements of $changed and the first $j elements
* of $other_changed both contain the same number of zeros
* (unchanged lines).
* Furthermore, $j is always kept so that $j == $other_len or
* $other_changed[$j] == false.
*/
while ($j < $other_len && $other_changed[$j])
$j++;
(from MediaWiki, the software which powers Wikipedia, an on-line collaborative encyclopedia)
Visual Basic
'
' Cut of HKEY_USERS\ if present.
' This makes interoperating with regedit easier.
'
If Len(SIDstring) > 11 Then
If Left(SIDstring, 11) = "HKEY_USERS\" Then
SIDstring = Mid(SIDstring, 12)
End If
End If
'
' Open the WMI Service and retrieve the SID
'
On Error Resume Next
Set SIDobject = GetObject( _
"winmgmts:{impersonationLevel=Impersonate}" _
).Get("Win32_SID.SID='" & SIDstring & "'")
If Err Then
MsgBox "Could not retrieve the SID.", vbOkOnly, "Sorry"
Exit Do
End If
(Adapted from an example illustrating ways to create system administration tools.)da:Kommentar de:Kommentar (Programmierung) fr:Commentaire ja:コメント (コンピュータ) pl:Komentarz (informatyka) ru:Комментарии (программирование)