Commenting style?

P

peter koch larsen

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
 
F

Francis Glassborow

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

Timo Geusch

James said:
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?
 
J

James Kanze

Timo said:
James Kanze 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.
 
S

Seungbeom Kim

James said:
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.
 
D

Dave Harris

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

Jorgen Grahn

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
 
J

Jorgen Grahn

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


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

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
 
I

Ian Collins

Jorgen said:
[c.l.c++.m trimmed]



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

Damien Kick

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

"empty" is neither a question nor a command. Merriam Websters says that
it can be an adjective, verb, or a noun. "is empty" is also neither a
question or a command but is rather a phrase devoid of meaning without
context. "x is empty" is perhaps a statement of fact, an implicit
question as to whether or not the statement of fact is true, or it could
possibly even a command; "it puts the lotion in the basket". "x is 12"
is not that far off from "let x be 12", neither of which are questions.
For example, Prolog uses "is" more like that in the above sense.

length( [], 0 ).
length( [_|Tail], X) :-
length(Tail, Y),
X is Y + 1.

Actually, the Prolog usage of 'is' is more of some kind of hybrid of a
question and a statement of fact. X is of some value if and only if, in
the context of the question being asked, the answer to the question is
yes when X is of that value. (Or something like that). "is x empty" is
probably only going to be a question, I suppose, though I'm sure
somebody could point out other possible interpretations. "if is x
empty" doesn't make any sense. "if x is empty" makes sense (and I'm
sure that it is this kind of usage which makes "is_empty" popular) but I
don't see how "x is empty" as a phrase without the context of the "if"
is not ambiguous. I mean, "x.is_empty()" without an "if" in front of it
almost reads like a command, e.g. "now x.is_empty()".

I would guess that the reason that you see no ambiguity in "is_empty" is
that you've adopted a convention of starting predicates with is/has but
I would suggest that there is nothing "natural" about this
interpretation. I use "is_empty" myself, too, but I don't pretend that
it is because of anything inherently obvious or "natural" about it. In
fact, probably the only naming convention that comes close to being
"natural" of which I'm aware would Scheme's use of '?', e.g. "empty?".
Of course, that is probably the one and only thing about Scheme which
might be called "natural". Any and all naming conventions are really
only going to be meaningful in the context of a community and the idioms
which have come to be used in that community. When it comes to C++, I
don't see how one can avoid the role of the C++ standard or its
influence in shaping what "is" or "is not" C++.
 
J

James Kanze

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

kevin cline

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.

If you keep functions small, so that the whole function can fit in your
head, then it doesn't much matter where the braces are. When I see

if (...)
{
for (...)
{
for (...)
{
if (...)
{
....
}
else
{
...
}
}
}
}
else
{
...
}

My head starts to hurt and again I don't much care where the braces
are. If I have to modify this function it's first going to become three
or four functions.
 
A

Angel Tsankov

Certainly. And there are two philosophies regarding the
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.

What kind of alignment are you talking about? Left or right?
 
J

James Kanze

"empty" is neither a question nor a command. Merriam Websters says that
it can be an adjective, verb, or a noun.

If it's the name of a function, it can only be a verb. My
Collins gives its use as a noun as "informal"; at any rate, I
can't off hand think of a use in programming where it would be a
noun. As an adjective, of course, it could easily be part of
the name of a variable (associated with a noun).
"is empty" is also neither a
question or a command but is rather a phrase devoid of meaning without
context. "x is empty" is perhaps a statement of fact, an implicit
question as to whether or not the statement of fact is true,

Except that we don't really have statements of fact in a
program. Given the context of use in a program, I don't see any
other reasonable way of interpreting x.is_empty() than as a
question, "is x empty?". (Similarly, I don't see any other
reasonable way of interpreting x.empty() than "empty x", i.e.
remove all elements from x. And of course, conventionally,
x.clear() would generally mean to return x to the state it had
immediatly after construction by the default constructor.)
 
D

Damien Kick

James said:
If it's the name of a function, it can only be a verb. My
Collins gives its use as a noun as "informal"; at any rate, I
can't off hand think of a use in programming where it would be a
noun. As an adjective, of course, it could easily be part of
the name of a variable (associated with a noun).


Except that we don't really have statements of fact in a
program.

Well, I had mentioned Prolog in the example and Prolog does have
statements of fact. Of course, this is c.l.c.m. However, even C++ has
statements of fact in the form of an assertion. One could even consider
something like the following

object.is_initialized()

in which case "is_initialized" returns true/false to indicate whether or
not the object has been successfully initialized, and so acts as both a
question (did it succeed?) and a command (do it). I would not do this
myself, instead preferring a constructor, but the usage seems perfectly
valid to me from the POV of it being a valid name for such a function.
> Given the context of use in a program, I don't see any
other reasonable way of interpreting x.is_empty() than as a
question, "is x empty?".

I read an interesting essay just last night, "Ambitious Evaluation: A
New Reading of an Old Issue" <http://tinyurl.com/2v5ama>, by Kent Pitman.

| It all started in 1986 when I was on staff at the MIT AI Lab and an
| undergrad studying Lisp asked me why the following piece of code
| didn't ``work'':
|
| (PROGN (SETQ *READ-BASE* 8.) 10)
| => 10. ; not 8.
|
| I chuckled for a moment with the kind of easy superiority that I have
|since learned to take as a sign that it's me, not the person I'm
| answering questions for, that really has something to learn.
|
| I answered the question in the obvious way, explaining how of course
| Lisp has to read the entire form into memory before it can execute any
| of it. So by the time the expression above has been processed by READ
| and is ready to have EVAL called, it is too late for any change to the
| setting of *READ-BASE* to affect it. The student was mostly happy with
| the explanation, but the more I thought about it, I was not.
|
| Increasingly, I've always found that the phrase ``of course'' is
| bandied about far too much, especially in computer science, a
| ``science'' which sometimes deals in provable facts (like algorithmic
| complexity) but that often deals in much more subjective,
| near-religious issues (like ``Fred implemented it this way, and Fred
| is generally right on such matters so everyone should do the same.'')
| as if they were facts.

It's a very interesting essay, in my opinion. He starts with "the only
reasonable way" to answer an undergraduate question but then begins
exploring an alternate approach to the question. From the "obvious"
beginning, he actually implements a perfectly reasonable version of read
and eval for which "(PROGN (SETQ *READ-BASE* 8.) 10)" evaluates to "8".
However, after having gone through a rather elaborate explanation,
including a working implementation of such a system, he writes the
following.

| My real goal here was partly to expose people to the way parsers and
| input editors are usually modularized in Lisp. And it was also partly
| to keep us all reminded that the reason we do things the way we do
| (e.g., separating input editing from parsing, and separating READ from
| EVAL) is not because it's the only way to do things, but because it's
| one of many design choices we had.
|
| The world is full of choices. Sometime an examination of the choices
| leads you to the same conclusion as you'd have arrived at without
| examining them. But looking over all of your options when making a
| design decision is always a good idea if you can spare the time.

At the end of the day, I really do agree with the idea of using "is_" as
a prefix for the name of a predicate because I do it, too. However, I
still believe that there is nothing "obvious" to any of it and that
there are other reasonable alternative interpretations. However, I
don't think that this topic has as much potential for depth to it as
Pitman's interesting journey from the obvious answer, to a working
contradiction of the obvious, only to return to agreeing with what was
the "obvious" answer in the first place. Especially as our topic of
what is is or is not is so fiercely subjective because, unlike Pitman's
exploration of read and eval, one can not do something like writing code
as a counter example of the "obvious". The argument can really only be
a bunch of people asserting that something is or is not obvious without
any hope of supporting his/her position besides simply repeating those
assertions. Unless, of course, we would attempt to make some kind of
argument based on linguistics, psychology, or something else relatively
off topic to c.l.c.m and for which I doubt any of us are qualified. And
again, at the end of the day, I would still use "x.is_foo()" in my C++
programs as "is x foo" and not "x is foo", too. And I'll use the
"obvious" reading of "X is Foo" as <pause> "X is Foo" when writing
Prolog or (is ?x ?foo) when writing Prolog in Lisp
(Similarly, I don't see any other
reasonable way of interpreting x.empty() than "empty x", i.e.
remove all elements from x. And of course, conventionally,
x.clear() would generally mean to return x to the state it had
immediatly after construction by the default constructor.)

Well, except that in this case, the only "reasonable way of interpreting
x.empty()" is wrong, isn't it? So just how "the only reasonable way"
can it be? And yet even though the standard manages to get the only
reasonable way wrong, "everybody" seems to be able to write working code
somehow, so just how unreasonable can it be? I agree that it is
probably inconsistent with the way some other functions are named but
all of the irregularities and inconsistencies in natural languages would
seem to suggest that people really don't have all that hard a time with
a certain level of inconsistency in their languages.
 
D

Dave Harris

What kind of alignment are you talking about? Left or right?

We're talking about left-aligning end of line comments, like:

int z; // Comment.
int y; // Another comment.
std::vector<double> x_intersections; // Yet another comment.

(You may need a mono-spaced font to see that.)

-- Dave Harris, Nottingham, UK.
 
T

Timo Geusch

Seungbeom said:
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.

Well, I wasn't really thinking about that kind of aesthetics but now
that you mention it...

I'm not a big fan on this kind of highlighting although I've worked in
places that make it mandatory and I can live with that.

I think the whole point here is that from looking at the code, you can
infer that the programmer cared; this doesn't mean that the code is
good but we'd probably all recoil in horror from the code we wrote as
novices. This is only part of the learning process and when you've been
doing it for a while you just learned that you have to carry on
learning :).

It's just my personal experience that code that looks like the
programmer cared about has a higher probability of being of decentish
quality, whereas programmers that don't care much about their code tend
to produce code with a higher probability of mistakes.

For me, aesthetics are mainly about code readbility - if it's easy to
follow then chances are it's good quality code because mistakes would
be more obvious compared to code that needs a pressure washer to clean
up.
 
F

Francis Glassborow

Timo Geusch said:
For me, aesthetics are mainly about code readbility - if it's easy to
follow then chances are it's good quality code because mistakes would
be more obvious compared to code that needs a pressure washer to clean
up.
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.

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)

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

Jerry Coffin

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

While I agree that comments are frequently overused, I think there are
times that comments make sense. In particular, comments can explain
_why_ you did something, whereas even the best-written code really only
explains what you did. An obvious example would be something like:

// insertion sort because the data is already nearly sorted.
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)

If I disagreed with that, it'd be that even 10% is to high.

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

Angel Tsankov

What kind of alignment are you talking about? Left or right?
We're talking about left-aligning end of line comments, like:

int z; // Comment.
int y; // Another comment.
std::vector<double> x_intersections; // Yet another
comment.

(You may need a mono-spaced font to see that.)

And what about:

int z; // Comment.
int y; // Another comment.
std::vector<double> x_intersections; // Yet another comment.
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,780
Messages
2,569,611
Members
45,280
Latest member
BGBBrock56

Latest Threads

Top