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! ]

[Francis Glassborow]

In article <45************ ***********@new s.sunsite.dk>, Angel Tsankov
<fn*****@fmi.un i-sofia.bgwrites

>And what about:

int z; // Comment.
int y; // Another comment.
std::vector<do ublex_intersect ions; // Yet another comment.

IMHO, madness. Allowing the longest typename control the position of the
names being declared (and do you propose to do the same for function
declarations? Or perhaps we should make sure all the assignment
operators are vertically aligned? :-)

The rules for code layout should be about readability. People will
disagree about the details. In ordinary text I have been taught to try
to avoid vertical alignment, particularly where the words are similar as
that inhibits easy reading by trapping the eye into skipping lines.
--
Francis Glassborow ACCU
Author of 'You Can Do It!' and "You Can Program in C++"
see http://www.spellen.org/youcandoit
For project ideas and contributions:
http://www.spellen.org/youcandoit/projects
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Timo Geusch]

Francis Glassborow wrote:

In article <xn************ ***@nermal.unix consult.co.uk>, Timo Geusch
<tn***@unixcons ult.co.ukwrites

For me, aesthetics are mainly about code readbility - if it's easy
to follow then chances are it's good quality code because mistakes
would be more obvious compared to code that needs a pressure washer
to clean up.

But for me, at least, code that reads cleanly with a minimum (zero
being the ideal) of comments is better than code which is laden with
comments. If the programmer really cares s/he will choose names etc.
that make most comments superfluous.

Oh, I agree - while it'll be hard to do Knuth-type literate programming
in C++, a decent programmer should make the code both readable and
comprehensible without the aid of too many comments such that the
comments are really reserved for the trickier bits.

--
The lone C++ coder's blog: http://www.bsdninjas.co.uk/codeblog/

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

[James Kanze]

Francis Glassborow wrote:

In article <45************ ***********@new s.sunsite.dk>, Angel Tsankov
<fn*****@fmi.un i-sofia.bgwrites

And what about:

int z; // Comment.
int y; // Another comment.
std::vector<dou blex_intersecti ons; // Yet another comment.

IMHO, madness. Allowing the longest typename control the position of the
names being declared (and do you propose to do the same for function
declarations? Or perhaps we should make sure all the assignment
operators are vertically aligned? :-)

The rules for code layout should be about readability. People will
disagree about the details. In ordinary text I have been taught to try
to avoid vertical alignment, particularly where the words are similar as
that inhibits easy reading by trapping the eye into skipping lines.

But code isn't ordinary text, and there are many cases where
using two dimensions can add to understandabili ty. The most
obvious is initialization lists; given something like:

struct MapInit
{
char const* key ;
int value ;
} ;
MapInit const initTable[] =
{
{ "one" , 1 },
{ "two" , 2 },
{ "three", 3 },
} ;

I cant' imagine not aligning. It's very much like a table in a
book or article (which would also be aligned). Because in C and
C++, declarations and expression statements are so
indistinguishab le, I've also adopted the policy of using a
special formatting for declarations: what is being declared is
always indented 20 spaces. It's arbitrary, but it does mean
that a declaration doesn't look like just another expression,
and draws attention to what is being declared. Other than that,
I do use a lot of vertical alignment, when I want to draw
attention to parallels in the code: if I'm assigning a sequence
of values, for example, I'll align the = signs, so that the
reader will immediately see the code for what it is: a sequence
of the same operations. Code is, on the whole, a lot less
verbose than normal text, and anything I can do to add semantic
content for the reader, I do.

--
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! ]

[Gennaro Prota]

On Tue, 23 Jan 2007 10:40:55 CST, Francis Glassborow wrote:

>But for me, at least, code that reads cleanly with a minimum (zero being
the ideal) of comments is better than code which is laden with comments.
If the programmer really cares s/he will choose names etc. that make
most comments superfluous.

This is something that I hear often. I think it only addresses a
specific category of comments (those that try compensating for bad
naming and bad coding practices in general).

>In fact when I see code that has more than about 10% inline comments I
begin to expect the worst (and if every line has a comment, I am pretty
certain that the comments will include serious mistakes)

Well, for one thing, code meant for automatic documentation extraction
(e.g. for doxygen) easily exceeds that number (or is "inline comment"
meant to exclude comments to be extracted?).

Apart from that, I'd be glad to know if your expectation-of-the-worst
is met with my code, which I guess has a relatively high number of
comments:

<http://breeze.svn.sour ceforge.net/viewvc/breeze/trunk/breeze/>

--
HELP: many of this group's participants might know that I'm the legit
~~~~ owner of the yahoo account with id 'gennaro_prota' ; I would be
immensely grateful to anyone who might help me gaining access
to it again (note that I'm now using the id 'gennaro.prota' ).
Thanks!

Genny.

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

[Noah Roberts]

[comp.lang.c++.m oderated removed - nothing ever came of previous attempt
to reply]

Gennaro Prota wrote:

Apart from that, I'd be glad to know if your expectation-of-the-worst
is met with my code, which I guess has a relatively high number of
comments:

<http://breeze.svn.sour ceforge.net/viewvc/breeze/trunk/breeze/>

I think you could cut down the size of your "header" comment a great
deal (where you explain the license and such. There are also many files
that have several lines of comment (like 100+) and only 5 lines of code
or so. This is a little excessive. Also this file in particular:

http://breeze.svn.sourceforge.net/vi...16&view=markup

There is more comment than code, as before, but worse...the code is
intermixed into the comments so you have like 100 lines of comment, a
line of code...20 lines of comment, a line of code, 10 lines of comment,
2 lines of code...etc...no t good. Makes the code pretty much
unreadable. What this illustrates is that in your projects the code has
less importance than the comment and it should be the other way around.

If you want to document the research you did it should be in a separate
file ... maybe even a paper. Your code shouldn't need a
bibliography... and yours has one. Yeah, credit where credit is
due...but put that somewhere else.

You asked...

[Jerry Coffin]

In article <bv************ *************** *****@4ax.com>, clcppm-
po****@this.is. invalid says...

[ ...]

Well, for one thing, code meant for automatic documentation extraction
(e.g. for doxygen) easily exceeds that number (or is "inline comment"
meant to exclude comments to be extracted?).

Comments to be extracted are normally not inline, but the extraction
isn't really the primary point. Inline comments are comments inline with
the code, intended to comment on a specific line of code. Header
comments that tell about the purpose of a routine (for example) aren't
inline comments. If you're using something like Doxygen, then yes, those
are (typically) the comments you format for extraction. Even if you
don't make any attempt at formatting them specifically for automatic
extraction, the same general kind of comment still isn't inline though.

Apart from that, I'd be glad to know if your expectation-of-the-worst
is met with my code, which I guess has a relatively high number of
comments:

<http://breeze.svn.sour ceforge.net/viewvc/breeze/trunk/breeze/>

Looking at a little of your code:

//
//! Generalized version of std::accumulate ().
//!
//! breeze::accumul ate_traits<is a customization
//! point: you are allowed to specialized it in
//! namespace breeze for your own type.
//

Most people would call this a block comment (or something similar). The
fact that it's formatted for automatic extraction is more or less beside
the point -- if you weren't using an automatic extraction tool, and
didn't do any special formatting on it for extraction, it'd still be a
block comment.

OTOH, it is more or less a one-way street: if you looked at some code
and decided something looked like a good candidate for automatic
extraction, that would probably be a fair indication that you were
looking at a block comment, not an inline comment.

template< typename InputIterator, typename T >
inline typename accumulate_trai ts< T >::result_typ e
accumulate( InputIterator begin,
InputIterator end,
T v = accumulate_trai ts< T >::first() )
{
return breeze::accumul ate_traits<
T >::compute( begin, end, v ); // gps qualify?

This one is an inline comment. It looks to me like an indication of
unfinished code -- it should really be replaced with a unit test that
proves one way or the other. It might well be appropriate to add a block
comment to that unit test to explain why it matters (assuming it's not
obvious to anybody who's familiar enough with your code to really care).

--
Later,
Jerry.

The universe is a figment of its own imagination.

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

[Noah Roberts]

Gennaro Prota wrote:

Apart from that, I'd be glad to know if your expectation-of-the-worst
is met with my code, which I guess has a relatively high number of
comments:

<http://breeze.svn.sour ceforge.net/viewvc/breeze/trunk/breeze/>

I think you could cut down the size of your "header" comment a great
deal (where you explain the license and such. There are also many files
that have several lines of comment (like 100+) and only 5 lines of code
or so. This is a little excessive. Also this file in particular:

http://breeze.svn.sourceforge.net/vi...16&view=markup

There is more comment than code, as before, but worse...the code is
intermixed into the comments so you have like 100 lines of comment, a
line of code...20 lines of comment, a line of code, 10 lines of comment,
2 lines of code...etc...no t good. Makes the code pretty much
unreadable. What this illustrates is that in your projects the code has
less importance than the comment and it should be the other way around.

If you want to document the research you did it should be in a separate
file ... maybe even a paper. Your code shouldn't need a
bibliography... and yours has one. Yeah, credit where credit is
due...but put that somewhere else.

You asked...

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

[Ryan Ply]

Noah Roberts <nr******@examp le.netwrites:

Gennaro Prota wrote:

Apart from that, I'd be glad to know if your expectation-of-the-worst
is met with my code, which I guess has a relatively high number of
comments:

<http://breeze.svn.sour ceforge.net/viewvc/breeze/trunk/breeze/>

I think you could cut down the size of your "header" comment a great
deal (where you explain the license and such. There are also many files
that have several lines of comment (like 100+) and only 5 lines of code
or so. This is a little excessive. Also this file in particular:

http://breeze.svn.sourceforge.net/vi...16&view=markup

There is more comment than code, as before, but worse...the code is
intermixed into the comments so you have like 100 lines of comment, a
line of code...20 lines of comment, a line of code, 10 lines of comment,
2 lines of code...etc...no t good. Makes the code pretty much
unreadable. What this illustrates is that in your projects the code has
less importance than the comment and it should be the other way around.

If you want to document the research you did it should be in a separate
file ... maybe even a paper. Your code shouldn't need a
bibliography... and yours has one. Yeah, credit where credit is
due...but put that somewhere else.

I agree. This style of commenting is better suited to Web than C++.

Ryan -

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

[James Kanze]

Noah Roberts wrote:

Gennaro Prota wrote:

Apart from that, I'd be glad to know if your expectation-of-the-worst
is met with my code, which I guess has a relatively high number of
comments:

<http://breeze.svn.sour ceforge.net/viewvc/breeze/trunk/breeze/>

I think you could cut down the size of your "header" comment a great
deal (where you explain the license and such. There are also many files
that have several lines of comment (like 100+) and only 5 lines of code
or so.

It all depends. I know that I once had a header with close to
2000 lines of comments, for about 300 lines of code. If the
header is being used as the external documentation of the class,
the case can occur. (To be fair, in my case, the header
contained the external documentation in two languages. But even
if I delete the French part, there will be close to 1000 lines
of comment.)

He's using the GNU licence, and I think his license text is
about right for this: copyright, a statement that the code is
under GPL, and an indication where you can get the full text.
I'd reorder it slightly, but that's about it.

This is a little excessive. Also this file in particular:

http://breeze.svn.sourceforge.net/vi...16&view=markup

There is more comment than code, as before, but worse...the code is
intermixed into the comments so you have like 100 lines of comment, a
line of code...20 lines of comment, a line of code, 10 lines of comment,
2 lines of code...etc...no t good. Makes the code pretty much
unreadable. What this illustrates is that in your projects the code has
less importance than the comment and it should be the other way around.

The file in question is a header, which contains (in this case)
the external documentation. Which means that the documentation
is more important than the code, since it determines what the
code should do. And I don't see any problem reading it: to
begin with, of course, syntax highlighting means that the
comments are of a different color. (Historically, I almost
always terminate a block comment with an underline, to separate
it from the code. I developed this habit in the days before
syntax highlighting, however; I doubt that it is that necessary
today.)

If you want to document the research you did it should be in a separate
file ... maybe even a paper. Your code shouldn't need a
bibliography... and yours has one. Yeah, credit where credit is
due...but put that somewhere else.

Why? So that it won't be updated when the file changes.
Anything which concerns just the contents of a single file
should be documented in that file, not elsewhere. (You often
need separate documentation as well, to give a larger, more
global view, with the relationships between classes.) On the
whole, I liked his documentation style (but that's probably
because it looks very much like my own).

--
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! ]

[Francis Glassborow]

In article <11************ *********@a75g2 000cwd.googlegr oups.com>, James
Kanze <ja*********@gm ail.comwrites

>Why? So that it won't be updated when the file changes.
Anything which concerns just the contents of a single file
should be documented in that file, not elsewhere. (You often
need separate documentation as well, to give a larger, more
global view, with the relationships between classes.) On the
whole, I liked his documentation style (but that's probably
because it looks very much like my own).

However I think such documentation should not make it hard to find the
code and scrolling down through several screens isn't exactly making
code accessible and readable. It would, I think, be helpful if the tools
that extract documentation also provided for the exclusion of the
documentation.

--
Francis Glassborow ACCU
Author of 'You Can Do It!' and "You Can Program in C++"
see http://www.spellen.org/youcandoit
For project ideas and contributions:
http://www.spellen.org/youcandoit/projects
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]