C.5. Comments

Avoid fancy layout or decoration in comments. The styles used are as follows:

/* single line comments look like this */

**  Important single line comments look like multi-line comments.

**  Multi-line comments look like this.  Put the opening and closing
**  comment sequences on lines by themselves.  Use complete sentences
**  with proper English grammar, capitalisation and punctuation.

/* but you don't need to punctuate or capitalise one-liners */

The opening forward slash (/) of all comments should be indented to the same level as the code to which it applies, for example:

if (fubar())
     /* Print a message before exiting. */
     ajFatal("Program is FUBAR");

Avoid placing comments on the same line as the code itself. If, for tidiness, they are deemed essential, then set it off from the code using spaces. Try to indent such comments to the same column and don't continue them across multiple lines:

func1();       /* useless comment */
func2();       /* useless comment */
func3();       /* useless comment */

See Section 3.1, “EMBOSS Programming” for guidelines on when and how to use comments.