[snips]
Since this thread is FUBAR I have to ask this - When commenting code:
what style is "the best" one? (Also: when commenting code: what style
do you use?)
The only "best" - objectively - is correct commenting; that is, the
comments explain what the code does, without being simply a repeat of the
code. "Add 1 to x", as a comment on a line reading x++; doesn't buy
anything. A comment should explain what a function or block (and
sometimes, depending how hairy the code is, line) is doing and, where
necessary, why it is doing it. It should also, at least for
function-level comments, give an indication of what inputs are acceptable
and what happens on errors, success, etc.
As to the *style*... well... that's one of those religious war type
questions. However, I'll suggest that the following are not the best:
/* this is */
/* a multi- */
/* line comment */
/****************
* this is *
* a multi- *
* line comment *
****************/
And other variations on the theme. Simply put, they're a pain in the
proverbials to update - and if they're a pain, chances are they won't be
updated. Contrast that to this:
/*
This is
a multi-
line comment
*/
If you need to add or change a line, you can focus on the "meat"; the
borders and whatnot don't get in your way. If you prefer comments to
really stand out, or have something you really need to draw attention to,
try this:
/*********************
This is an important
comment. Please
read it.
********************/
Stands out, will be found readily by even casual visual inspection of the
code, yet it's still readily editable.
KISS is the guiding principle, IMO. Skip the fancy formatting; that makes
it less editable, less likely to be correctly maintained. Use a format
which a developer busy concentrating on other things can modify the
comment easily and efficiently and he's going to be a lot more likely to
keep those comments current and correct.