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

[Dave Harris]

ke*********@gma il.com (kevin cline) wrote (abridged):

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.

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.

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

[James Kanze]

Seungbeom Kim wrote:

Gerhard Menzl wrote:

Dave Harris wrote:

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

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.

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

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.

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

[Gerhard Menzl]

Seungbeom Kim wrote:

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

[clcppm-poster]

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.

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

[Earl Purple]

Alf P. Steinbach wrote:

* mlimber:

On a personal note, I prefer not to use the preprocessor to "comment
out" code like Satish does above. Instead I use // comments throughout
and use /**/ comments to get rid of blocks and/or regular expression
search-and-replace to add // to the beginning of each line I want to
comment out.

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]

Seungbeom Kim wrote:

Gerhard Menzl wrote:

Dave Harris wrote:

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

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

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

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

[James Kanze]

Stephan Kuhagen wrote:

Keith H Duggar wrote:

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

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

[James Kanze]

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

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

[Stephan Kuhagen]

James Kanze wrote:

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]

Diego Martins wrote:

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