Jump to content

Comment (computing)

From Wikipedia, the free encyclopedia

This is an old revision of this page, as edited by Nickj (talk | contribs) at 04:44, 27 March 2005 (close <code> tag - WP:WS). The present address (URL) is a permanent link to this revision, which may differ significantly from the current revision.

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.

Comments should either summarise code or explain the programmer's intent, why rather than how - the two are often close, but not always. It is less useful to restate the code in plain English, a waste of time, or explain the code - if code is that complex it 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)

Comment styles are usually agreed before a project starts. The style should be easy to modify and difficult to break, for example the In-context examples below show block comments with marks only on one side rather than complete boxes - which look nice but 'break' easily and so discourage changes leading to out-of-date comments. The examples also show poor variable naming. Different styles can be chosen for different areas of code, from individual lines to paragraphs, routines, files, and programs. Although line and endline comments should be used rarely - only for data declarations, to mark blocks, and to note later modifications. Style can also differentiate major and minor comments, such as dashes in front of minor comments, but this can often cause later difficulties.

Certain projects try and define rules like "a comment every ten lines," this can be counterproductive. Similarly over-complex routine-level comments can be wasteful.

Some programmers use syntactically incorrect comments to mark errors so the program will not compile with the 'comment', and so the error, in place.

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.

Examples

(the word "comment" is used here, as an example of a comment):

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.

In-context examples

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)

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)

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)

Retrieved from "https://en.wikipedia.org/w/index.php?title=Comment_(computing)&oldid=11904783"