Commenting style?

[Angel Tsankov]

Can someone recommend a good source of C/C++ coding style.
Specifically, I am interested in commenting style and in
particular how to indent comments and the commented code, rather
than when to use comments. Thanks in advance!
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[James Kanze]

Dave Harris wrote:

fn*****@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: ja*********@gma il.com
Conseils en informatique orientée objet/
Beratung in objektorientier ter Datenverarbeitu ng
9 place Sémard, 78210 St.-Cyr-l'École, France, [phone]
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[James Kanze]

Seungbeom Kim wrote:

And I'd like to add that good comments describe *why* something is done,
rather than *what* is done by the code (which the code already says).

Within a function, about the only comments I use are ones to
explain why some simple solution wasn't used. Commenting what
you didn't do, and why (i.e. the alternatives that you
considered and rejected), is often more useful than commenting
what you actually ended up doing. Presumably, the reader can
read C++, and can recognize the usual patterns and familiar
algorithms, and knows when and why they are used. Why some
apparently simpler solution wasn't appropriate is often more
useful information.

--
James Kanze (Gabi Software) email: ja*********@gma il.com
Conseils en informatique orientée objet/
Beratung in objektorientier ter Datenverarbeitu ng
9 place Sémard, 78210 St.-Cyr-l'École, France, [phone]
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Noah Roberts]

..moderated removed to allow free discussion.

Alf P. Steinbach wrote:

* Noah Roberts:

My personal preference is to follow the smells theory in which code
commenting is a smell:

Depends on the kind of comment.

Well, code smells are all about "depends".

"Note that a CodeSmell is a hint that something might be wrong, not a
certainty. A perfectly good idiom may be considered a CodeSmell because
it's often misused, or because there's a simpler alternative that works
in most cases. Calling something a CodeSmell is not an attack; it's
simply a sign that a closer look is warranted. "

http://c2.com/xp/CodeSmell.html

So everything you say may be true but doesn't contradict the "comments
are smells" theory.

[Dave Harris]

ke*********@gma il.com (kevin cline) wrote (abridged):

I prefer to move such blocks into separate functions, and then use the
comment for the function name.

Sometimes splitting code over separate functions help, and sometimes it
doesn't. Sometimes in order to understand the code I need to see it all in
one place; get it all in my head at once. For example, a variable may be
set up in one block and used in another, and these may be coupled such
that the blocks are hard to understand in isolation. You need to see how
it is used before you understand why it is set up in that particular way,
or vice-versa.

The idea that the function names should be the comments sounds fine, but I
don't find it works in practice. I like my comments to be written in plain
English, which is too wordy for function names. Verbose function names are
less readable than (reasonably) terse ones.

Here's an example to clarify:

/// Return true if this list has no members.
bool MyList::empty() const {
return head_ != NULL;
}

The comment is eight words rather than one. It explains what "empty"
means; once you know the explanation the word itself is enough, but I find
it does help to explain it somewhere once for people who don't know. When
I am reading other people's code there often seems to be a lot of
information in the author's mind that didn't make it into the code,
including a special vocabulary. Comments can help correct that.

Even if the function name is sufficient (which admittedly is probably the
case with such a standard name as "empty"), there is often more to say:

/// This is guaranteed O(1) where size() may be O(N).
bool MyList::empty() const {
return head_ != NULL;
}

That comment is for users of the function. Similar comments can explain
the implementation:

// Find the largest item. Although this looks like an O(N*N)
// algorithm, it is actually O(N) because the widget is memoised.

-- Dave Harris, Nottingham, UK.

--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Angel Tsankov]

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.

Can you point out such an editor?

>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.

Again: example of an editor providing this functionality?
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Roy Smith]

br******@cix.co .uk (Dave Harris) wrote:

/// Return true if this list has no members.
bool MyList::empty() const {
return head_ != NULL;
}

The comment is eight words rather than one. It explains what "empty"
means; once you know the explanation the word itself is enough, but I find
it does help to explain it somewhere once for people who don't know. When
I am reading other people's code there often seems to be a lot of
information in the author's mind that didn't make it into the code,
including a special vocabulary. Comments can help correct that.

Even if the function name is sufficient (which admittedly is probably the
case with such a standard name as "empty"), there is often more to say:

/// This is guaranteed O(1) where size() may be O(N).
bool MyList::empty() const {
return head_ != NULL;
}

Not to mention the possibility that it might have been:

/// Empty the list
void MyList::empty() {
head_ = NULL;
}

Granted, seeing it used in context, or seeing that the return type is bool
would be pretty good clues that "empty" is being used as a predicate, not a
verb. But, my point is that what's obvious to the author is often not
obvious to a reader many years later.

--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Ian Collins]

Dave Harris wrote:

>
The idea that the function names should be the comments sounds fine, but I
don't find it works in practice. I like my comments to be written in plain
English, which is too wordy for function names. Verbose function names are
less readable than (reasonably) terse ones.

Here's an example to clarify:

/// Return true if this list has no members.
bool MyList::empty() const {
return head_ != NULL;
}

The comment is eight words rather than one.

What's wrong with isEmpty()? Sums up the comment and is unambiguous.

--
Ian Collins.

[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Keith H Duggar]

Seungbeom Kim wrote:

That style of commenting falls into the same category as
this:

++x; // increment x

and I would object to it, unless the code is for
exposition of the relevant part of the language in a C++
textbook.

/** First Paragraph */
This is a good observation. Perhaps such comments should
also be avoided in textbooks as well? Those who learn from
such books may come to believe this is good style (after all
it's in a book!) and hence fall into the habit of writing
such useless comments. // End First Paragraph

/** Second Paragraph */
Books are not ASCII source code and are not bound by it's
limitations. Authors are free to use a variety of expository
tools (tables, line numbers, weights, styles, colors, etc)
and I have seen all these alternatives used in programming
textbooks. So don't we set a bad example by choosing the
useless redundant comment tool? // End Second Paragraph

/** Author */
Keith
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[James Kanze]

Angel Tsankov wrote:

[...]

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.

Can you point out such an editor?

Emacs has it more or less built into the C++ mode; you can't
avoid it. I use vim, and it's auto-indentation does pretty much
the same thing (although it's no where near as sophisticated
about it as vim).

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.

Again: example of an editor providing this functionality?

Vi requires the extra command. Emacs does it more or less
automatically.

Every editor I've ever used (well, since ed), has had the
possibility of filtering lines of text through an external
program. This is what I used with vi. Editors like emacs have
a built in programming language, so you don't even need an
external filter.

--
James Kanze (GABI Software) email:ja******* **@gmail.com
Conseils en informatique orientée objet/
Beratung in objektorientier ter Datenverarbeitu ng
9 place Sémard, 78210 St.-Cyr-l'École, France, [phone]
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[kevin cline]

Dave Harris wrote:

ke*********@gma il.com (kevin cline) wrote (abridged):

I prefer to move such blocks into separate functions, and then use the
comment for the function name.

Sometimes splitting code over separate functions help, and sometimes it
doesn't. Sometimes in order to understand the code I need to see it all in
one place; get it all in my head at once. For example, a variable may be
set up in one block and used in another, and these may be coupled such
that the blocks are hard to understand in isolation.

Convert the first block into a function returning the value, then pass
it into a second function. If the first block computes multiple
values, then that data should probably be collected into a class.

You need to see how
it is used before you understand why it is set up in that particular way,
or vice-versa.

The idea that the function names should be the comments sounds fine, but I
don't find it works in practice. I like my comments to be written in plain
English, which is too wordy for function names. Verbose function names are
less readable than (reasonably) terse ones.

Here's an example to clarify:

/// Return true if this list has no members.
bool MyList::empty() const {
return head_ != NULL;
}

The comment is eight words rather than one. It explains what "empty"
means;

If you had named the function "isEmpty" instead of "empty", you could
probably live without the comment. Empty is rather a poor name, since
"Empty the trash" means to make the waste container empty. To find out
if the container is empty, we say "If the wastebasket is empty ..."

I am reading other people's code there often seems to be a lot of
information in the author's mind that didn't make it into the code,
including a special vocabulary. Comments can help correct that.

Better naming works wonders, but first one has to see a program with
consistently good naming. In my experience, few programmers have seen
such a program.

Even if the function name is sufficient (which admittedly is probably the
case with such a standard name as "empty"), there is often more to say:

/// This is guaranteed O(1) where size() may be O(N).
bool MyList::empty() const {
return head_ != NULL;
}

I never suggested that a function should not have a comment describing
it's purpose or performance. I merely suggested that blocks that are
large enough to require commenting are large enough to be extracted
into a separate function.
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]