473,799 Members | 3,147 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Commenting style?

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

Jan 11 '07
100 4767
Noah Roberts wrote:
Dave Harris wrote:
>ia******@hotmai l.com (Ian Collins) wrote (abridged):
>>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.
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++.

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

Jan 21 '07 #71

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

Jan 21 '07 #72
>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.
What kind of alignment are you talking about? Left or right?
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.)

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

Jan 21 '07 #73
Damien Kick wrote:
Noah Roberts wrote:
Dave Harris wrote:
ia******@hotmai l.com (Ian Collins) wrote (abridged):
>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.
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.
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.)

--
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, +33 (0)1 30 23 00 34
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

Jan 21 '07 #74
James Kanze wrote:
Damien Kick wrote:
>Noah Roberts wrote:
>>Dave Harris wrote:
ia******@hotmai l.com (Ian Collins) wrote (abridged):
>>>>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
specialise d vocabularies that need to be documented.
>>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.

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.
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_initi alized()

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
<http://tinyurl.com/24b3uu>.
(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.

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

Jan 21 '07 #75
fn*****@fmi.uni-sofia.bg (Angel Tsankov) wrote (abridged):
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<dou blex_intersecti ons; // Yet another comment.

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

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

Jan 23 '07 #76
Seungbeom Kim wrote:
James Kanze wrote:
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.
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.

--
The lone C++ coder's blog: http://www.bsdninjas.co.uk/codeblog/

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

Jan 23 '07 #77
In article <xn************ ***@nermal.unix consult.co.uk>, Timo Geusch
<tn***@unixcons ult.co.ukwrites
>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++.m oderated. First time posters: Do this! ]

Jan 23 '07 #78
In article <6s************ **@robinton.dem on.co.uk>,
fr*****@robinto n.demon.co.uk says...

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

Jan 24 '07 #79
>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<dou blex_intersecti ons; // 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<dou blex_intersecti ons; // Yet another comment.
--
[ See http://www.gotw.ca/resources/clcm.htm for info about ]
[ comp.lang.c++.m oderated. First time posters: Do this! ]

Jan 24 '07 #80

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

46
2499
by: Profetas | last post by:
Hi, I know that this is off topic. but I didn't know where to post. Do you comment your source code while coding or after coding. for example: you write a procedure and after it is working, you'll comment it.
9
1879
by: | last post by:
Does C++/CLI have XML style commenting like C#?? If i do /// I dont get the completion like C#
8
1866
by: lallous | last post by:
Hello I've been programming for a number of years, however my commenting style is always different. Sometimes I use something like: /************************ * method .... * comments... *************************/
0
9688
marktang
by: marktang | last post by:
ONU (Optical Network Unit) is one of the key components for providing high-speed Internet services. Its primary function is to act as an endpoint device located at the user's premises. However, people are often confused as to whether an ONU can Work As a Router. In this blog post, we’ll explore What is ONU, What Is Router, ONU & Router’s main usage, and What is the difference between ONU and Router. Let’s take a closer look ! Part I. Meaning of...
0
10491
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. Here is my compilation command: g++-12 -std=c++20 -Wnarrowing bit_field.cpp Here is the code in...
0
10268
jinu1996
by: jinu1996 | last post by:
In today's digital age, having a compelling online presence is paramount for businesses aiming to thrive in a competitive landscape. At the heart of this digital strategy lies an intricately woven tapestry of website design and digital marketing. It's not merely about having a website; it's about crafting an immersive digital experience that captivates audiences and drives business growth. The Art of Business Website Design Your website is...
1
10247
by: Hystou | last post by:
Overview: Windows 11 and 10 have less user interface control over operating system update behaviour than previous versions of Windows. In Windows 11 and 10, there is no way to turn off the Windows Update option using the Control Panel or Settings app; it automatically checks for updates and installs any it finds, whether you like it or not. For most users, this new feature is actually very convenient. If you want to control the update process,...
0
10031
tracyyun
by: tracyyun | last post by:
Dear forum friends, With the development of smart home technology, a variety of wireless communication protocols have appeared on the market, such as Zigbee, Z-Wave, Wi-Fi, Bluetooth, etc. Each protocol has its own unique characteristics and advantages, but as a user who is planning to build a smart home system, I am a bit confused by the choice of these technologies. I'm particularly interested in Zigbee because I've heard it does some...
0
6809
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert into image. Globals.ThisAddIn.Application.ActiveDocument.Select();...
0
5593
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
4146
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system
3
2941
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating effective websites that not only look great but also perform exceptionally well. In this comprehensive...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.