Next: , Previous: , Up: Tips and Standards   [Contents][Index]


C.2 Tips on Writing Comments

Here are the conventions to follow when writing comments.

#

Comments that start with a single sharp-sign, ‘#’, are used to explain the code on the same line as the comment itself. These comments should all be aligned to the same column to the right of the source code. In the Emacs mode for Octave, the M-; (indent-for-comment) command automatically inserts such a ‘#’ in the right place, or aligns such a comment if it is already present. Example:

C = 2 * pi * r;    # formula for circumference of a circle
##

Comments that start with a double sharp-sign, ‘##’, are stand-alone comments that occupy an entire line. These comments should be aligned to the same level of indentation as the code. Such comments usually describe the purpose of the following lines or the state of the program at that point. Example:

## Calculate area and volume of a sphere
A = 4 * pi * r^2;
V = 4/3 * pi * r^3;

The indentation commands of the Octave mode in Emacs, such as M-; (indent-for-comment) and TAB (octave-indent-line) automatically indent comments according to these conventions, depending on the number of semicolons. See Manipulating Comments in The GNU Emacs Manual.