Commenting style?

[kevin cline]

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.

 

[Steven E. Harris]

Can you point out such an editor?

Emacs: "/ runs `c-electric-slash'."

Again: example of an editor providing this functionality?

Emacs: "M-q runs `c-fill-paragraph'."

 

[Stephan Kuhagen]

/** 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

Sometimes the "book" and the source code are the same thing, as in literate
programming. For a real world example, have a look at "Physically Based
Rendering" from Matt Pharr and Greg Humphreys. The layout of the book is
amazing, the source code (c++) is perfectly readable and has perfectly
helpful documentation.

So it is possible to achieve good documentation, readable layout with lots
of additional information and maintainable source at once. But I can't
imagine, how much discipline it takes to consequently follow the rules of
such documentation style. And the worst is, currently there are very few
tools that help, to do this kind of intermixed coding/documenting.

Regards
Stephan

 

[Dave Harris]

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

"IsEmpty" is hardly better than "empty" in that both assume the reader
knows what "empty" means. As I explained, projects often develop
specialised vocabularies that need to be documented.

(What's wrong with "isEmpty" specifically is that it's inconsistent with
std::vector; but we're surely talking general principles here and don't
want to nit-pick details of the examples.)

-- Dave Harris, Nottingham, UK.

 

[Ian Collins]

"IsEmpty" is hardly better than "empty" in that both assume the reader
knows what "empty" means. As I explained, projects often develop
specialised vocabularies that need to be documented.

If a team or project has an established metaphor, it doesn't require
explanatory comments in the code. If anywhere, such documentation
belongs in the project documentation or Wiki.

 

[Alf P. Steinbach]

* Dave Harris:

"IsEmpty" is hardly better than "empty" in that both assume the reader
knows what "empty" means. As I explained, projects often develop
specialised vocabularies that need to be documented.

(What's wrong with "isEmpty" specifically is that it's inconsistent with
std::vector; but we're surely talking general principles here and don't
want to nit-pick details of the examples.)

Conforming to a convention just for conformance's sake is seldom a good
idea.

The C++ standard library constitutes a fine set of examples of how to
/not/ name things, a standardized "worst practice", which it's not a
good idea to conform to -- presumably the idea was to force novice C++
programmers to struggle with these names and so understand, from the
inflicted pain, what to avoid in their own code (it would be nice to
also have a set of "best practice" examples in the standard, carrots in
addition to the sticks, and there are some, e.g. the names 'list' and
'vector', which are short, readable and self-documenting names, but
unfortunately only the stick method of providing how-not-to-do-it
examples now seems to be in vogue with the international C++ committee,
and now applied also to the language itself, e.g. 'declspec').

And 'empty' is perhaps one of the best of these "worst practice"
examples, because it's short and readable and actually related to what
the function accomplishes, while suggesting something else, namely
suggesting an action (make empty) instead of a check (is empty), thus
sending the unsuspecting novice in the wrong direction first.

--
A: Because it messes up the order in which people normally read text.
Q: Why is it such a bad thing?
A: Top-posting.
Q: What is the most annoying thing on usenet and in e-mail?

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

 

[Gerhard Menzl]

"IsEmpty" is hardly better than "empty" in that both assume the reader
knows what "empty" means. As I explained, projects often develop
specialised vocabularies that need to be documented.

Knowing what "empty" means does not resolve the ambiguity, which is
caused by the nature of the English language: little inflectional and
conjugational variation, usage of words both as verbs and adjectives.
Thus the word "empty" by itself could either be interpreted as an
imperative ("empty!"), or as an abbreviated question ("empty?").

I prefer to prefix boolean queries with "is" or "has" because it avoids
unnecessary mental effort on the part of the reader.

(What's wrong with "isEmpty" specifically is that it's inconsistent
with std::vector; but we're surely talking general principles here and
don't want to nit-pick details of the examples.)

The C++ Standard Library naming convention is not very helpful in that
empty() is used as an adjective (query), but clear() as a verb
(command). Obviously, terseness was valued higher than intuitive
understanding.

--
Gerhard Menzl

Non-spammers may respond to my email address, which is composed of my
full name, separated by a dot, followed by at, followed by "fwz",
followed by a dot, followed by "aero".



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

 

[Martin Eisenberg]

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.

Do you know one (or more whose code is public?


Martin

 

[Noah Roberts]

"IsEmpty" is hardly better than "empty" in that both assume the reader
knows what "empty" means. As I explained, projects often develop
specialised vocabularies that need to be documented.

Is "empty" a question or command? I don't see that ambiguity with
"is_empty".

 

[Seungbeom Kim]

Knowing what "empty" means does not resolve the ambiguity, which is
caused by the nature of the English language: little inflectional and
conjugational variation, usage of words both as verbs and adjectives.
Thus the word "empty" by itself could either be interpreted as an
imperative ("empty!"), or as an abbreviated question ("empty?").

I prefer to prefix boolean queries with "is" or "has" because it avoids
unnecessary mental effort on the part of the reader.

Then how would you name a function that does the emptying action?
make_empty()?

The C++ Standard Library naming convention is not very helpful in that
empty() is used as an adjective (query), but clear() as a verb
(command). Obviously, terseness was valued higher than intuitive
understanding.

I think the C++ Standard Library established the convention anyway,
no matter how bad some people may argue it is (because it is "the"
standard). Then following the already-established convention certainly
has its merits, because people already know it.

 

[Dave Harris]

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.

I'm well aware of the "method object" pattern. I use it when it is
appropriate. It's not always appropriate. I think you missed the point
about how separating production from consumption can make the code harder
to understand.

Empty is rather a poor name

I agree, but it is the name used by the standard library.

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.

I have seen such. I've even written such. And if your naming is going to
be consistent, and it is also going to use std::vector, then it has to use
"empty".

-- Dave Harris, Nottingham, UK.

 

[Gerhard Menzl]

Then how would you name a function that does the emptying action?
make_empty()?

My convention follows the pattern "is/has" + adjective/noun for boolean
queries and verb [+ object] for commands. I would therefore have no
problems with is_empty() and empty(). Since the latter stands alone, it
must be a verb.

--
Gerhard Menzl

Non-spammers may respond to my email address, which is composed of my
full name, separated by a dot, followed by at, followed by "fwz",
followed by a dot, followed by "aero".



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

 

[James Kanze]

Then how would you name a function that does the emptying action?
make_empty()?

The general rule is that function names are verbs or verbal
phrases. Given empty(), in this context, "empty" must be a
verb, and says what is done to the object.

I think the C++ Standard Library established the convention anyway,
no matter how bad some people may argue it is (because it is "the"
standard). Then following the already-established convention certainly
has its merits, because people already know it.

The problem is that it is in contradiction with every other
existing standard (including common English usage). The basic
first rule of naming is that types are unqualified nouns,
objects, qualified nouns and functions, verbs. There are
exceptions, of course: many people prefer using qualified nouns
for attributes, even if in C++ what the client uses are actually
accessor functions (getters and setters). But the basic
principle is there, and as a function, empty() can ONLY mean
empty the collection.

 

[clcppm-poster]

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.

 

[Earl Purple]

* mlimber:

Agreed that // comments are less visually imposing. And it's a shame
that /*...*/ don't nest, necessitating using condititional compilation
as a commenting-out device.

It's also that several code editors that use colour for syntaxing will
not mark the
commented out code as a comment in pre-processors so it is an effort to
see that
it is actually commented out.

 

[Diego Martins]

Then how would you name a function that does the emptying action?
make_empty()?


I think the C++ Standard Library established the convention anyway,
no matter how bad some people may argue it is (because it is "the"
standard). Then following the already-established convention certainly
has its merits, because people already know it.

bool myclass::empty() const; will be always a query. I can't see any
ambiguity with that

I believe in shorter names and self documentation coming from a
(member-)function interface; although I agree on additional comments
like // O(1)

Diego Martins
HP

 

[James Kanze]

Keith H Duggar wrote:

Sometimes the "book" and the source code are the same thing, as in literate
programming. For a real world example, have a look at "Physically Based
Rendering" from Matt Pharr and Greg Humphreys. The layout of the book is
amazing, the source code (c++) is perfectly readable and has perfectly
helpful documentation.

So it is possible to achieve good documentation, readable layout with lots
of additional information and maintainable source at once. But I can't
imagine, how much discipline it takes to consequently follow the rules of
such documentation style. And the worst is, currently there are very few
tools that help, to do this kind of intermixed coding/documenting.

What about CWeb? If I were writing a book, I'm pretty sure that
that's what I'd use (but maybe only because I don't know of
anything else).

 

[James Kanze]

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

 

[Stephan Kuhagen]

What about CWeb? If I were writing a book, I'm pretty sure that
that's what I'd use (but maybe only because I don't know of
anything else).

Yes, CWeb would be also the first thing I'd look at. But there are very few
tools out there, that does something like it (and even fewer people know
about or consider using them). For the book, I mentioned, the authors
implemented their own tool... I think, the idea of literate programming is
a very good approach towards readable documentation, but the
usability/availability of the tools is "improvable". That is a pity,
because literate programming has (or had, maybe the chance is gone?) IMHO
the potential for establishing some techniques for better documentation.

Regards
Stephan

 

[Gerhard Menzl]

bool myclass::empty() const; will be always a query. I can't see any
ambiguity with that

Providing you are looking at the prototype or function definition. The
meaning of the function is much harder to figure out when all you are
looking at is a call to it, especially when it is part of a complicated
expression. A verb-based naming convention (which would suggest is_empty
for a query) can improve readability.

--
Gerhard Menzl

Non-spammers may respond to my email address, which is composed of my
full name, separated by a dot, followed by at, followed by "fwz",
followed by a dot, followed by "aero".



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