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

[Gennaro Prota]

Collapsing two replies into one, for easier "management ":

--
1. On Sun, 28 Jan 2007 22:49:51 CST, Jerry Coffin wrote:

>Looking at a little of your code:

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.

Yes. You caught one of my famous (! ;-)) temporary comments (for the
record, 'g' and 'p' in "gps" are my initials; 's' is a... secret :-)).
They are markers for issues I want to think further about, and won't
ever get into releases (it should be evident that the code isn't at a
release stage: the project front page reports "planning" development
status, and no unit tests have been committed yet, though of course I
have them).

>It looks to me like an indication of unfinished code

Indeed. Or rather of code that I'm aware to be unfinished (I might
consider "finished" lot of things which actually aren't :-)).

--
2. On Sun, 28 Jan 2007 22:52:13 CST, Noah Roberts wrote:

>I think you could cut down the size of your "header" comment a great
deal (where you explain the license and such.

I already (tried to) cut it down, and it is shorter than what

<http://www.gnu.org/licenses/gpl.html#SEC4>

recommends (as well as shorter than the average prologues I find in
open source headers). For one thing I omitted the no-warranty
disclaimer.

I'd remove the part which says to write to the FSF in case no copy of
the license accompanies the code, too, if only I were sure that the
removal is allowed (I was assured that my other snips *are* legally
fine).

>[...]

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.

Well, not sure your general point holds, but that file is a particular
case, anyway (note the todo markers as well).

>[...]

You asked...

Sure :-) If one exposes his/her code publicly s/he must be willing to
accept criticisms. And I even asked for it :-)

BTW, one of the Breeze (ambitious) goals is to encourage adoption, and
centralized development/testing, of "modern C++" into the open source
world; with few exceptions I have noticed that open source C++ is on
average a "C with classes", and I think we can have much better than
that (the best C++ is IMHO much more *reliable* than the best C or C
with classes). I think everyone will benefit from a wider use of more
robust techniques (we all have a Linux box, don't we?) so some of the
comments in my code are "didactic", to say so. Despite that, I don't
think they would be much different in a production environment, at
least in an environment where the effort to write such comments would
be adequately appreciated.
--
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! ]

[Allan W]

Dave Harris wrote:

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.

Ian Collins wrote:

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

We still don't know what "Empty" means.

Consider a MyList of std::string.
Empty might mean: All of the strings on this list are 0-length.
Or it might mean: There aren't any strings on this list.
Or it might mean: All of the strings on this list contain only
whitespace.

Dave Harris's meaning is consistent with the STL, but it's dangerous
to
assume that every author means the same thing... until you see Dave's
8-word comment, which confirms the assumption.
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

[Allan W]

Francis Glassborow wrote:

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)

Wow, I completely disagree with this.

It could be due to my background; I programmed for some time in
assembly
language, where it's customary to put a comment on almost every line
of
source code.

This isn't always my style when I code in C++ -- but I always think
about it,
and decide if the code deserves this or not. And it isn't rare that it
does.
Of course, the comment must never explain WHAT we're doing (the reader
is expected to know the language), but WHY we're doing it... so if
that's
exceptionally obvious, the comment goes away. But very often there's
at least something minimal I can say on 80% or more of my source
lines.

And yes, this does mean that if the code changes, the comments have to
change too... leaving obsolete comments with improved code, is simply
criminal. Better to remove the comments, then to leave in comments
that aren't true anymore. Very early in my career I made this mistake
a
few times, but it's been many years.
--
[ 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 <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.

You almost always have to do so, however, because of various
copyright messages, etc., imposed by the legal department. And
of course, with any decent editor, it's only one or two
keystrokes; with vim, at least (and I suppose with most other
editors), you can even set things up so the editor automatically
opens the file with the cursor positionned after the headers.

And of course, I would consider the documentation as part of the
code---in the header files I looked at, for example, the code
was totally uninteresting; the only reason to open the files at
all would be to look at the documentation. If you're modifying
something, of course, you should modify the documentation first,
then the code. At any rate, the documentation here is at least
as important as the code.

It would, I think, be helpful if the tools
that extract documentation also provided for the exclusion of the
documentation.

Isn't it more the editor's problem. You want the documentation
as close to what is being documented as possible, so as to
reduce the likelyhood of it not being updated when the code is
updated. Some people will still forget, but the good
programmers will first update the documentation, to reflect the
new contract, and then the code.

--
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************ **********@q2g2 000cwa.googlegr oups.com>, Allan
W <al*****@my-dejanews.comwri tes

>Francis Glassborow wrote:

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

Wow, I completely disagree with this.

It could be due to my background; I programmed for some time in
assembly
language, where it's customary to put a comment on almost every line
of
source code.

But I also come from a background of programming in assembler but that
is a very different environment. For example, I can recall a time when I
was coding a sort routine for strings in z80 assembler, needless to say
almost every line was commented so that I could keep track of what I was
doing.

However high level languages provide other powerful ways to describe
what the code is doing, and the most effective is often in writing the
code so it documents itself.

When I look at code published by generally accepted experts (Stroustrup,
Sutter, Alexandrescu etc.) I find their inline comments to be generally
sparse other than those used for tutorial purposes. In addition to
blocks of comments giving design details, there is also the use of brief
comments that act rather like sub-heads:

class C {
public:
// ctors

// conversions

//assignments

// mutating functions

// const functions

//operators

//io support

}:

I have no problem with such a style and it does tend to help maintenance
programmers put additions into the right place (and helps them see what
has already been provided)

However I will stick with my critical view of code packed with inline
comments, not least because they obscure the 'shape' of the code. I once
commented that the best thing about colour coded syntax was that one
could code comments as white on white, and often benefited from doing so
:-)

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

[Gennaro Prota]

On Tue, 30 Jan 2007 10:26:07 CST, James Kanze wrote:

>Francis Glassborow wrote:

>[...]
It would, I think, be helpful if the tools
that extract documentation also provided for the exclusion of the
documentatio n.

Isn't it more the editor's problem. You want the documentation
as close to what is being documented as possible, so as to
reduce the likelyhood of it not being updated when the code is
updated. Some people will still forget, but the good
programmers will first update the documentation, to reflect the
new contract, and then the code.

110% agreement here. And I'll also add that doing so helps the
programmer himself: it might seem all crystal clear in your mind (and
it sometimes is :-)) but writing things down will almost always
clarify important details you hadn't thought of. And, of course, the
most important points to update are those that can't be expressed in
code (C++09's concepts will help in this regard, but there are other
non-codifiable aspects, of course).

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

[Angel Tsankov]

--
Angel Tsankov
fn*****@fmi.uni-sofia.bg
"Francis Glassborow" <fr*****@robint on.demon.co.ukw rote in
message news:Vi******** ******@robinton .demon.co.uk...

In article
<11************ **********@q2g2 000cwa.googlegr oups.com>, Allan
W <al*****@my-dejanews.comwri tes

>>Francis Glassborow wrote:

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

Wow, I completely disagree with this.

It could be due to my background; I programmed for some time in
assembly
language, where it's customary to put a comment on almost every
line
of
source code.

But I also come from a background of programming in assembler
but that
is a very different environment. For example, I can recall a
time when I
was coding a sort routine for strings in z80 assembler,
needless to say
almost every line was commented so that I could keep track of
what I was
doing.

However high level languages provide other powerful ways to
describe
what the code is doing, and the most effective is often in
writing the
code so it documents itself.

When I look at code published by generally accepted experts
(Stroustrup,
Sutter, Alexandrescu etc.) I find their inline comments to be
generally
sparse other than those used for tutorial purposes. In addition
to
blocks of comments giving design details, there is also the use
of brief
comments that act rather like sub-heads:

class C {
public:
// ctors

// conversions

//assignments

// mutating functions

// const functions

//operators

//io support

}:

I have no problem with such a style and it does tend to help
maintenance
programmers put additions into the right place (and helps them
see what
has already been provided)

Separating member functions (and member data, or course) into
sections seems a very good idea indeed. I would like to call for
more opinions and styles of sectioning since I have found that
putting order in long class definitions makes them much more easy
to understand and maintain.
In particular, I wonder if it is a good idea to separate mutating
from const functions, e.g. setters and getters. Instead, I would
prefer grouping member functions based on some higher level
criteria. For instance, if a class implements an interface, the
interface members should be put in their own section titled
"IfaceX implementation" or something. Likewise, ctors and dtor
could reside in a section titled "Constructi on and destruction",
for example. And prorably it is a good idea to put this section
before other sections in the class definition. Also, it might be
fine I tell which members are implicitly defined for a class:

class C
{
////////////////////////////////////////////////////////
// Construction and destruction
////////////////////////////////////////////////////////
public:
// Uses implicit default ctor
// Uses implicit copy ctor
// Uses implicit dtor
};
[ 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:

[...]

When I look at code published by generally accepted experts (Stroustrup,
Sutter, Alexandrescu etc.) I find their inline comments to be generally
sparse other than those used for tutorial purposes.

Just a reminder that the constraints on publishing code are
considerably different than those on code developed and
maintained in industry. As it happens, I find that in-line
comments are very sparse there as well, at least in my own
code. But for decidely different reasons than when I'm
publishing. When I've published, block comments have also
been exceedingly sparse; in industry, on the other hand,
it's not rare for over half the lines of a header file to be
block comments.

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

Angel Tsankov wrote:

"Francis Glassborow" <fr*****@robint on.demon.co.ukw rote in
message news:Vi******** ******@robinton .demon.co.uk...

[...]

class C {
public:
// ctors

// conversions

//assignments

// mutating functions

// const functions

//operators

//io support

}:

I have no problem with such a style and it does tend to
help maintenance programmers put additions into the
right place (and helps them see what has already been
provided)

Separating member functions (and member data, or course) into
sections seems a very good idea indeed. I would like to call for
more opinions and styles of sectioning since I have found that
putting order in long class definitions makes them much more easy
to understand and maintain.

Avoiding long class definitions entirely helps even more:-).
(Regretfully, it's not always possible.)

In particular, I wonder if it is a good idea to separate mutating
from const functions, e.g. setters and getters. Instead, I would
prefer grouping member functions based on some higher level
criteria. For instance, if a class implements an interface, the
interface members should be put in their own section titled
"IfaceX implementation" or something. Likewise, ctors and dtor
could reside in a section titled "Constructi on and destruction",
for example. And prorably it is a good idea to put this section
before other sections in the class definition. Also, it might be
fine I tell which members are implicitly defined for a class:

I agree with all points. The public section of my classes
always starts with a section "constructo rs, destructor and
assignment" (which also includes swap, when present). The
comments in this section explicitly mention anything
intentionally left to the compiler, If copy construction or
assignment has been inhibited by making them private, this
fact is also mentionned there.

Beyond that, functions are grouped. By interface and/or
concept, where relevant. A class which acts in some ways
like an STL container, for example, will have begin(),
end(), front() and back() all together, const and non-const
versions, because STL container is a concept.

When implementing an interface or a concept, it's not rare
for me to use grouping, and no further comments for those
functions except a statement that the group implements such
and such a concept.

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

[Angel Tsankov]

[...]

class C {
public:
// ctors

// conversions

//assignments

// mutating functions

// const functions

//operators

//io support

}:

I have no problem with such a style and it does tend to
help maintenance programmers put additions into the
right place (and helps them see what has already been
provided)

>Separating member functions (and member data, or course) into
sections seems a very good idea indeed. I would like to call
for
more opinions and styles of sectioning since I have found that
putting order in long class definitions makes them much more
easy
to understand and maintain.

Avoiding long class definitions entirely helps even more:-).
(Regretfully, it's not always possible.)

Sure, it does!

>In particular, I wonder if it is a good idea to separate
mutating
from const functions, e.g. setters and getters. Instead, I
would
prefer grouping member functions based on some higher level
criteria. For instance, if a class implements an interface,
the
interface members should be put in their own section titled
"IfaceX implementation" or something. Likewise, ctors and dtor
could reside in a section titled "Constructi on and
destruction" ,
for example. And prorably it is a good idea to put this
section
before other sections in the class definition. Also, it might
be
fine I tell which members are implicitly defined for a class:

I agree with all points. The public section of my classes
always starts with a section "constructo rs, destructor and
assignment" (which also includes swap, when present). The
comments in this section explicitly mention anything
intentionally left to the compiler, If copy construction or
assignment has been inhibited by making them private, this
fact is also mentionned there.

Beyond that, functions are grouped. By interface and/or
concept, where relevant. A class which acts in some ways
like an STL container, for example, will have begin(),
end(), front() and back() all together, const and non-const
versions, because STL container is a concept.

When implementing an interface or a concept, it's not rare
for me to use grouping, and no further comments for those
functions except a statement that the group implements such
and such a concept.

Well, could you share some ideas about formatting and delimiting
those sections?
How do you specify which members are implicitly defined and
which - inacessible?
Do you happen to explain why you have chosen to make the
respective members inaccessible?
How do you specify that a class implements a concept like STL
container?
Probably it is also a good idea to mention (when appropriate, of
course) that a class is part of a design pattern especially when
the pattern involves other classes as well, isn't it? If so, how
should I make this clear?
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]