Commenting code
In computer programming, comments are a part of code which is used to explain the code; such comments are generally ignored by compilers and executions. 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.
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.
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 () {
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 the Wikipedia PHP script)
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)
|
