Commenting

The main principle is that your programs should be readable by someone who understands both the problem domain and the C programming language -- as much as possible, code should be simple, clear, and obvious (this is not always easy to achieve). You do not need to explain the problem domain, although in some cases you could include a reference to external documentation about the problem domain.

You definitely should not explain the C programming language to your reader. The canonical bad comment style is:

	i++;  /* add one to i */

One reason that this is bad is that it takes longer to read the comment than to read the C code. The comment detracts from the program; it makes it less clear.

Another reason is that over time, comments like that tend to turn into comments like this:

	i += 2;  /* add one to i */

In general, you should try to avoid saying identical things in multiple places. You're already familiar with this idea with respect to avoiding duplicated code. I would like to suggest that this applies just as much to comments which echo the code.

So if you shouldn't write comments like the above, what should you write?

One form of comments is as a guide to the code. Don't say things which echo the code, but say things which explain what the various bits of the code are doing on a higher level.

Files usually begin with a "prologue comment" which says the purpose of the program, in a single-file program, or the purpose of this file (module), in a multi-file program.

Functions often could use an introductory comment, which traditionally appears prior to the function header. This could state the specification of the function in higher-level terms. It could state some preconditions, and/or it could explain edge cases of the function behaviour or return values. Comments which appear outside the function should usually describe the external behaviour of the function, not its implementation, unless the implementation is particularly relevant (e.g. if it is a fast one as opposed to a more usual algorithm for that operation). Again it should not echo the code; don't say that a function returns int in English; say it in C (which you are already doing). And don't write blather just because you can't think of anything better to say. If you have nothing to say, don't say it.

Similarly, some introductory notes inside the function might explain (or reference) the algorithm. But only if it is interesting and unobvious.

A common style is to divide your code into "paragraphs", separated by a blank line, in which the first line of most paragraphs is a comment (on its own line) saying what happens next, in high-level terms. E.g. "check that we're not overwriting an existing file", "convert parameters to one-origin", etc. Ideas which are not a repetition of the code but are a more general description of what is going on.

"Marginal notes" comments usually appear on the same line as the code they refer to, after the code (i.e. on the right). They clarify minor points. Example:

	p += 2;  /* skip the semicolon and the space */

If major points need clarification, you could insert a large (non-marginal) comment before the code in question. Often at this point we instead write a separate text file and just refer to that file in comments. Much better is to rewrite the code so that it isn't so confusing as to need major clarification, although admittedly this isn't always possible, but often it is.

Generally speaking, it's better to improve unclear code than to comment it. For example, don't write the comment

	int x;  /* the number of lines */

	int nlines;

Another source of bad code which should be rewritten rather than commented is when functions do not encapsulate a natural idea. Each function should perform a task which can be clearly stated.

On another note, please keep in mind that you are formatting your program to look good on all displays, not just your own. For example, if you have lines wider than 80 characters, you might be tempted simply to resize your window so that it's wider than 80 characters. But you can't resize the windows of all of the people reading your code. Keep in mind that your readers' windows might be as little as 80 characters wide. (Sometimes long strings exceed 80 characters anyway and this is ok, so long as you realize it will wrap around on some people's computers.)

Similarly, a tab character represents spacing to the next multiple of 8 spaces. Your editor might have a command (or menu item) which says to change what the "tab stops" are. You should not use this command. Because again, you are affecting only your own viewing experience, not everyone else's. If you use a different editor, if you use the same editor from a different account or on a different computer, if you display the file with "cat" or print it with "lpr", it will be presented with 8-character tab stops.

If your editor has an option to use a different number of spaces when you press the tab key, this is not a problem, so long as when your editor writes out the file, it uses tabs to represent 8-character tab stops only. (E.g. some such editors don't write out tab characters on output at all; the tab key is just used as a handy data entry method in the editor, and all output to the file uses appropriate numbers of spaces.)