Re: Commenting style?
fn42551@fmi.uni-sofia.bg (Angel Tsankov) wrote (abridged):
I also agree about endline comments. Steve McConnell, for
instance, recommends using endline comments in the following
cases: to annotate data declarations; and to mark the end of a
block [Code Complete, 2nd Edition].
In my view ends of blocks don't generally need comments to mark them.
However, the following question arises with endline comments: Should
one try to indent adjacent endline comments so that they start on
the same column?
If I have more to say than will fit at the end of the line, I make it a
normal comment on the line above. I don't have set places for using
endline comments. I use them whenever the comment is short and I want to
save space.
I think trying to line up comments with tabs or spaces is a mugs game.
Including things like:
int x; // Some value.
std::vector<int> table; // Some other value.
It's just too much trouble to maintain. If the vector changes to something
longer, the comment indent will have to change and I'll have to go back
and reformat the other comments too. And although it looks prettier I
don't believe it is any easier to read.
For instance, I might decide that the commented code needs some
empty lines which, on second glance, makes me think exactly which
lines of code the comments applies to.
It can't be helped. Credit readers with some intelligence; they'll figure
it out. The comments give them some hints but if they really need to know
what's going on they'll read the code itself. Code is definitive. Comments
aren't.
If you must, you can put another comment at the end of the code or at the
start of the next code. Or put braces around it all and let the reader
figure out that the comment applies to all the code inside the braces. The
situation is rare enough that common sense solutions surely suffice.
Should one use a ful lstop (.) to mark the end of sentences?
I think so, yes. I tend to write comments in English, with normal English
punctuation. That's kinda the point: they are not supposed to be code.
And does this apply to all types of comments (full-line, endline,
C-style, C++-style)?
Yes. (I rarely use C-style comments, if by that you mean /* */.)
-- Dave Harris, Nottingham, UK.
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]