Commenting style?

[Francis Glassborow]

And what about:

int z; // Comment.
int y; // Another comment.
std::vector<double> x_intersections; // 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++.moderated. First time posters: Do this! ]

 

[Timo Geusch]

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.

 

[James Kanze]

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 understandability. 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
indistinguishable, 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.

 

[Gennaro Prota]

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

 

[Noah Roberts]

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

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.sourceforge.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/v...iom/bool_testable.hpp?revision=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...not 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]

[ ...]

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.sourceforge.net/viewvc/breeze/trunk/breeze/>

Looking at a little of your code:

//
//! Generalized version of std::accumulate().
//!
//! breeze::accumulate_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_traits< T >::result_type
accumulate( InputIterator begin,
InputIterator end,
T v = accumulate_traits< T >::first() )
{
return breeze::accumulate_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++.moderated. First time posters: Do this! ]

 

[Noah Roberts]

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.sourceforge.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/v...iom/bool_testable.hpp?revision=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...not 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...

 

[Ryan Ply]

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/v...iom/bool_testable.hpp?revision=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...not 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 -

 

[James Kanze]

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:

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

 

[Francis Glassborow]

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++.moderated. First time posters: Do this! ]

 

[Gennaro Prota]

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

--

Looking at a little of your code:

template< typename InputIterator, typename T >
inline typename accumulate_traits< T >::result_type
accumulate( InputIterator begin,
InputIterator end,
T v = accumulate_traits< T >::first() )
{
return breeze::accumulate_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 ).

--

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/v...iom/bool_testable.hpp?revision=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...not 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.

 

[Allan W]

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.

 

[Allan W]

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.

 

[James Kanze]

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.

 

[Francis Glassborow]

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++.moderated. First time posters: Do this! ]

 

[Gennaro Prota]

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

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.

 

[Angel Tsankov]

--
Angel Tsankov
(e-mail address removed)-sofia.bg

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 "Construction 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++.moderated. 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]

message news:[email protected]...

[...]

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 "Construction 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 "constructors, 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.

 

[Angel Tsankov]

[...]

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

Sure, it does!

I agree with all points. The public section of my classes
always starts with a section "constructors, 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?