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

[peter koch larsen]

cl***********@t his.is.invalid wrote:

On 13 Jan 2007 15:59:57 -0500, Dave Harris wrote:

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. [...] And although it looks

prettier

I don't believe it is any easier to read.

I hope this won't create an uproar but one shouldn't underestimate the
good effects of pleasure (I mean of the spirit :-)). Our mood does
affect our activities, especially the mental ones.

I agree with you fully on this one. I just love to work with nice and
well structured code (and hate the pasta-like alternatives). It is also
easier to find bugs and/or enhance such code.

/Peter
--
[ 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************ **********@11g2 000cwr.googlegr oups.com>, James
Kanze <ja*********@gm ail.comwrites

>I think it also passes an important message: that the programmer
cared about the code he was writing. (But not aligning things
doesn't mean that the programmer doesn't care. If it's aligned,
he probably cared; if it's not, you don't know, unless there are
other signs---and there almost always are, if he did care.)

And if it isn't aligned it may well be that that is an artefact of the
editor he used and the one you are using to read his code (or even the
configuration details of the respective editors)
--
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]

James Kanze wrote:

cl***********@t his.is.invalid wrote:

On 13 Jan 2007 15:59:57 -0500, Dave Harris wrote:

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. [...] And although it
looks prettier I don't believe it is any easier to read.

I hope this won't create an uproar but one shouldn't underestimate
the good effects of pleasure (I mean of the spirit :-)). Our mood
does affect our activities, especially the mental ones.

Agreed. I'd rather maintain esthetically pleasing code.

I think it also passes an important message: that the programmer
cared about the code he was writing. (But not aligning things
doesn't mean that the programmer doesn't care. If it's aligned,
he probably cared; if it's not, you don't know, unless there are
other signs---and there almost always are, if he did care.)

How often do you see someone doing something they really care about in
a sloppy fashion?

While code that looks estetically pleasing to me may not look the same
to you - after all, countless flamewars have been fought about the most
important question ever in the proramming universe, namely where the
curly braces go - at least a consistent layout with a minimum of
formatting and well tought-out variable names would suggest that the
original author of the code cared about what e was doing.

Once you find three to four different styles of indentation in a single
file then I would put the probability of the file containing bugs at
80% plus...

Guess who's currently working on software that has dark corners with
strangely formatted files and long functions in said files that tend to
contain multiple declarations of "int i" within said long functions?

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

Timo Geusch wrote:

James Kanze wrote:

cl***********@t his.is.invalid wrote:

On 13 Jan 2007 15:59:57 -0500, Dave Harris wrote:

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. [...] And although it
looks prettier I don't believe it is any easier to read.

I hope this won't create an uproar but one shouldn't underestimate
the good effects of pleasure (I mean of the spirit :-)). Our mood
does affect our activities, especially the mental ones.

Agreed. I'd rather maintain esthetically pleasing code.

I think it also passes an important message: that the programmer
cared about the code he was writing. (But not aligning things
doesn't mean that the programmer doesn't care. If it's aligned,
he probably cared; if it's not, you don't know, unless there are
other signs---and there almost always are, if he did care.)

How often do you see someone doing something they really care about in
a sloppy fashion?

Never.

While code that looks estetically pleasing to me may not look the same
to you - after all, countless flamewars have been fought about the most
important question ever in the proramming universe, namely where the
curly braces go - at least a consistent layout with a minimum of
formatting and well tought-out variable names would suggest that the
original author of the code cared about what e was doing.

Certainly. And there are two philosophies regarding the
alignment of opening comments. I like them aligned; Dave Harris
doesn't think it matters. Both are valid viewpoints, just like
the position of the opening brace. If you see them aligned, you
know that the programmer cared. You also know that he thought
it mattered. If you don't see them aligned, you don't know
whether it was because he didn't care, or because he simply
didn't feel that it mattered.

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

[Seungbeom Kim]

James Kanze wrote:

Agreed. I'd rather maintain esthetically pleasing code.

I think it also passes an important message: that the programmer
cared about the code he was writing. (But not aligning things
doesn't mean that the programmer doesn't care. If it's aligned,
he probably cared; if it's not, you don't know, unless there are
other signs---and there almost always are, if he did care.)

The message it brings is that the programmer cared about the aesthetics
of the code, not necessarily the working quality of the code. I've seen
lots of (novice) programmers who write poor quality code but care a lot
about its decoration, spending time on drawing big boxes of asterisks
around only a few lines of the actual comments.

--
Seungbeom Kim

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

[Dave Harris]

ja*********@gma il.com (James Kanze) wrote (abridged):

Certainly. And there are two philosophies regarding the
alignment of opening comments. I like them aligned; Dave Harris
doesn't think it matters.

Actually my position is more anti than my earlier remark suggested. I
think end-comments are often easier to read if they are not aligned. If
you have some very short declarations, and one or more long ones, then the
long one pushes the comment so far to the right, and so far from the the
short ones, that it can be hard to see which comment goes with which
declaration.

My editor can't align end-of-line comments automatically, but if it could
I'd switch the feature off.

There are other cases where prettiness is counter-productive. For example,
justified text looks cleaner but is harder to read than ragged-right
because irregularity helps the eye keep track of where it is.

(There are also cases where it helps, of course. It can highlight symmetry
and make column-selections more useful.)

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

[Jorgen Grahn]

On Fri, 12 Jan 2007 19:21:36 -0500, noone <no***@all.comw rote:
....

I have no preference regarding whitespace in
expressions and deviate in style there myself.

I think and hope you mean something like "... and use different styles
depending on the circumstances, in a way I cannot express in the form of
rules".

I can accept styles that don't look like mine, and I think style should
change depending on the thing you try to implement -- but I cannot tolerate
when people have /no/ style, and write more or less at random.

/Jorgen

--
// Jorgen Grahn <grahn@ Ph'nglui mglw'nafh Cthulhu
\X/ snipabacken.dyn dns.org R'lyeh wgah'nagl fhtagn!

[Jorgen Grahn]

[c.l.c++.m trimmed]

On 13 Jan 2007 00:46:54 -0500, kevin cline <ke*********@gm ail.comwrote:

>
Satish wrote:

>Basically attached is the class layout and source code layout... You
can see the comments section. Also if you want to comment a large
piece of code but at the same time you don't want to delete the code
use #ifdef like

#ifdef JUST_FOR_COMMEN TING_OUT
code here which you dont want to execute
#endif

"#if 0" is mush more obvious, IMHO. It cannot mean anything else.
(But if you use this in code someone else ever sees, you really need a system
for revision control instead.)

>>
############## CLASS LAYOUT######### ############### ##
/**
* A one line description of the class.
*
* #include "XX.h" <BR>
* -llib
*
* A longer description.
*
* @see something
*/

Here he's are assuming that the header file encapsulates a class and nothing
else. That's pretty common I guess, but you might equally well have
namespaces, templates, functions, more related classes ...

All the comments that follow are completely useless. They consume
screen space while adding no information, merely stating what is
obvious to a C++ programmer with more than a month's experience. Code
is much easier to read and understand when it is uncluttered.

Yes. I used that commenting style in my very first C++ programs way back,
and it just looks silly today.

IMHO, for a class, the most important part is the documented purpose and
limitations of the class as a whole. Surprisingly often, the rest is taken
care of with good function and parameter names.

/Jorgen

--
// Jorgen Grahn <grahn@ Ph'nglui mglw'nafh Cthulhu
\X/ snipabacken.dyn dns.org R'lyeh wgah'nagl fhtagn!

[Ian Collins]

Jorgen Grahn wrote:

[c.l.c++.m trimmed]

On 13 Jan 2007 00:46:54 -0500, kevin cline <ke*********@gm ail.comwrote:

>>Satish wrote:

>>>Basically attached is the class layout and source code layout... You
can see the comments section. Also if you want to comment a large
piece of code but at the same time you don't want to delete the code
use #ifdef like

#ifdef JUST_FOR_COMMEN TING_OUT
code here which you dont want to execute
#endif

"#if 0" is mush more obvious, IMHO. It cannot mean anything else.
(But if you use this in code someone else ever sees, you really need a system
for revision control instead.)

Why bother? Just delete the code and recover it from version control if
you want it back.

--
Ian Collins.

[James Kanze]

Seungbeom Kim wrote:

James Kanze wrote:

Agreed. I'd rather maintain esthetically pleasing code.

I think it also passes an important message: that the programmer
cared about the code he was writing. (But not aligning things
doesn't mean that the programmer doesn't care. If it's aligned,
he probably cared; if it's not, you don't know, unless there are
other signs---and there almost always are, if he did care.)

The message it brings is that the programmer cared about the aesthetics
of the code, not necessarily the working quality of the code. I've seen
lots of (novice) programmers who write poor quality code but care a lot
about its decoration, spending time on drawing big boxes of asterisks
around only a few lines of the actual comments.

There's esthetics, and esthetices. Drawing big boxes of
asterisks is ugly (but not much extra effort if you have the
right tools); the only place I'd use it is at the top (the
copyright header). Caring about *superficial* decoration is not
caring about the code you are writing.

With regards to aligning end of line comments, to be frank, it's
rarely an issue, since I don't use them much. If I have a
series of anything parallel, however (assignments, end of line
comments, etc.), I rather like to align them to stress the
parallelism. I'll also line up initializers in an agglomerate
initialization, if possible. (And as Dave Harris pointed out,
this causes problems if one individual right-hand side element
is much longer than the others. As with any rule, it's not
perfect, and you must weigh the pro's and the contra's in each
case.)

FWIW: I don't do this by hand. I have various programs which to
it for me. (At least with emacs and vim, it's easy to pass a
block of code through an external filter, so you have all the
power of C++ at your disposition for special formatting.)

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