Re: Commenting style?
Dave Harris wrote:
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.
Unless your functions are too complex. (But of course, the
solution is to simplify the function, not to comment the end of
the blocks.)
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.
I think you really can't avoid it, if the editor is set up
right. As soon as you enter //, the editor moves it over to the
predefined column.
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.
I'd expect any editor worthy of the name to do this
automatically. At the very most, you must enter a short command
to ask it to reformat the comments for an entire block.
And although it looks prettier I
don't believe it is any easier to read.
I think it depends. If you don't have syntax highlighting, it
definitly helps finding the comment, or even recognizing that
the comment is there. (But about the only time I can imagine
not having syntax highlighting is when printing to a black and
white printer.)
In practice, end of line comments are very, very rare in my code
anyway. I comment the class (using Doxygen), and the functions
there, and have almost no comments in the actual code. About
the only place I end up with end of line comments is for things
like enum values, and even then, most of the time, a couple of
them need more.
--
James Kanze (Gabi Software) email: james.kanze@gmail.com
Conseils en informatique orient?e objet/
Beratung in objektorientierter Datenverarbeitung
9 place S?mard, 78210 St.-Cyr-l'?cole, France, +33 (0)1 30 23 00 34
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.moderated. First time posters: Do this! ]