By Jack Ganssle

Comments on Comments

Published 3/13/2007

In-line comments should be outlawed.

You know the ones, like this:

a= out_pr * scale; // scale the input

Code infested with this commenting strategy invariably, especially after long in maintenance, looks like a bar-hopper weaving his drunken way down the street. Like this:

scale_ad(base_val);  // set A/D ref
base_val=offset/2; // adjust by power of two
hypotenuse=sqrt(side_a*side_a+side_b*side_b); // find side

Comments are supposed to be distinct from the code. Though part of the program, they present the information in a different sort of context, and may be read independently of the code. But, as this example shows, your eyes struggle to find where the C ends and the comments begin.

Usually we start a project determined to write pretty code, and craft a rule to start all comments in a particular column. That lines things up beautifully, but greatly increases the hassle of maintenance. Change just a single character and you've got to realign the starting pair of slashes. Why force developers to work so hard? Especially when we know, under deadline pressure, we won't?

This artificial demarcation means it's hard to fit a statement in the allotted space before the "//". Sure, it's possible to continue a C statement over multiple lines, but breaking up a statement in a comprehensible way, especially when using long variable names, can be hard.

With comments appended to the C lines there's an essential tension between keeping the C short so as to not run into the double slashes, and picking a starting line number not so high that all of the comments start in a column waaaay out to the right, pushed off the screen of a reasonably-sized editor window.

The decision to start a line of documentation on, say, line 60 limits the length of the comment. We remove words, context and meaning to fit the comment into the 20 or 40 characters left before the end of the editor window. What should be "disable all safety warnings" gets compressed to "dis warns," leaving some future maintainer to wonder why we'd want to dis anyone, let alone a warning.

I prefer using comment blocks, which are large enough to permit a complete description. So

/* 
   Adjust the input by "scale", which
   is the coefficient calculated at
   calibration time.
*/

is far better than

a= out_pr * scale; // scale the input
             

(In assembly, where each instruction does so little and the mnemonics are short, in-line comments are fine).

Obviously, this is my opinion. Yours may differ. What is your C commenting strategy?