C++ Programming Style Guidelines

[E. Robert Tisdale]

C++ Programming Style Guidelines

http://geosoft.no/development/cppstyle.html

I think that these guidelines are almost *all* wrong.
For example:

11. Private class variables should have underscore suffix.
class SomeClass {
private:
int length_;
}

12. Generic variables should have the same name as their type.
void setTopic (Topic *topic)
// NOT: void setTopic (Topic *value)
// NOT: void setTopic (Topic *aTopic)
// NOT: void setTopic (Topic *x)

void connect (Database *database)
// NOT: void connect (Database *db)
// NOT: void connect (Database *oracleDB)

7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

[David Lee Conley]

"E. Robert Tisdale" <E.**************@jpl.nasa.gov> wrote in message
news:d8**********@nntp1.jpl.nasa.gov...

C++ Programming Style Guidelines

http://geosoft.no/development/cppstyle.html

I think that these guidelines are almost *all* wrong.
For example:

11. Private class variables should have underscore suffix.
class SomeClass {
private:
int length_;
}

12. Generic variables should have the same name as their type.
void setTopic (Topic *topic)
// NOT: void setTopic (Topic *value)
// NOT: void setTopic (Topic *aTopic)
// NOT: void setTopic (Topic *x)

void connect (Database *database)
// NOT: void connect (Database *db)
// NOT: void connect (Database *oracleDB)

7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

I definitely don't agree with #7. I may be new to this, but I'm pretty sure
this violates one of the basic principles of OOD: polymorphism. Why use two
names for a function when you can overload it?

employee.Name(); matrix.Element(2, 4);
employee.Name(name); matrix.Element(2, 4, value);

Dave

[Fraser Ross]

"E. Robert Tisdale"

C++ Programming Style Guidelines

http://geosoft.no/development/cppstyle.html

I think that these guidelines are almost *all* wrong.
For example:

11. Private class variables should have underscore suffix.
class SomeClass {
private:
int length_;
}
It doesn't say why not to do this with all class members and I don't know a
reason.
7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

The functions have different purposes so I agree with giving them different
names.

Fraser.

[Howard]

"David Lee Conley" <co********@earthlink.net> wrote in message
news:ti****************@newsread3.news.atl.earthli nk.net...

7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

I definitely don't agree with #7. I may be new to this, but I'm pretty
sure this violates one of the basic principles of OOD: polymorphism. Why
use two names for a function when you can overload it?

employee.Name(); matrix.Element(2, 4);
employee.Name(name); matrix.Element(2, 4, value);

Dave

I disagree. Polymorphism has to do with objects of different types
accomplishing the same task with their own methods, such as a Rectangle and
a Circle both performing a Draw function. The task is to"draw". How they
do it is what differs. And that's accomplished by overriding virtual
functions, not by overloading.

(That's run-time polymorphism, anyway. There's also compile-time
polymorphism, using templates, but again, that has to do with working with
different types, not making one name stand for different actions on a single
type.)

A function called "Name" tells you nothing... it's not a verb, which is what
a function name should usually be. It should tell you what it does.

Also, suppose you want to have a default parameter for your function? How
would you accomplish that in your scenario? You can't, because leaving out
the name (or value) parameter suddenly changes the meaning of the function
call from a setter to a getter.

If you use accessor functions, then calling them getWhatever and setWhatever
sound like perfectly reasonable requirements to me. Giving them just the
name of the member variable does not.

-Howard

[David Lee Conley]

"Howard" <al*****@hotmail.com> wrote in message
news:10*********************@bgtnsc04-news.ops.worldnet.att.net...

"David Lee Conley" <co********@earthlink.net> wrote in message
news:ti****************@newsread3.news.atl.earthli nk.net...

7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

I definitely don't agree with #7. I may be new to this, but I'm pretty
sure this violates one of the basic principles of OOD: polymorphism. Why
use two names for a function when you can overload it?

employee.Name(); matrix.Element(2, 4);
employee.Name(name); matrix.Element(2, 4, value);

Dave

I disagree. Polymorphism has to do with objects of different types
accomplishing the same task with their own methods, such as a Rectangle
and a Circle both performing a Draw function. The task is to"draw". How
they do it is what differs. And that's accomplished by overriding virtual
functions, not by overloading.

(That's run-time polymorphism, anyway. There's also compile-time
polymorphism, using templates, but again, that has to do with working with
different types, not making one name stand for different actions on a
single type.)

A function called "Name" tells you nothing... it's not a verb, which is
what a function name should usually be. It should tell you what it does.

Also, suppose you want to have a default parameter for your function? How
would you accomplish that in your scenario? You can't, because leaving
out the name (or value) parameter suddenly changes the meaning of the
function call from a setter to a getter.

If you use accessor functions, then calling them getWhatever and
setWhatever sound like perfectly reasonable requirements to me. Giving
them just the name of the member variable does not.

-Howard

You're right. I should've put more thought into it. My bad.

Dave

[John Dibling]

E. Robert Tisdale wrote:

I think that these guidelines are almost *all* wrong.
I agree, and here's one I particularly hate:
49. [snip] Note that structs are kept in C++ for compatibility with C only,
and avoiding them increases the readability of the code by reducing the number of constructs used. Use a class instead.

This implies that it's never correct to define a datatype that is just
a bag of bits, such as:

struct Name
{
std::string m_sFirst, m_sLast;
};

This implication is nonsensical and overly restrictive. The fact that
C++ gives the programmer many ways to accomplish a given task is a
*good* thing, not a bad thing. Everything must not necesarrily be a
full-fledged object.

[Shezan Baig]

John Dibling wrote:

E. Robert Tisdale wrote:

I think that these guidelines are almost *all* wrong.

I agree, and here's one I particularly hate:

49. [snip] Note that structs are kept in C++ for compatibility with C only,
and avoiding them increases the readability of the code by reducing the number of constructs used. Use a class instead.

This implies that it's never correct to define a datatype that is just
a bag of bits, such as:

struct Name
{
std::string m_sFirst, m_sLast;
};

This implication is nonsensical and overly restrictive. The fact that
C++ gives the programmer many ways to accomplish a given task is a
*good* thing, not a bad thing. Everything must not necesarrily be a
full-fledged object.

You guys should read the "disclaimer" at the beginning, goes something
like this:

"The attempt is to make a guideline, not to force a particular coding
style onto individuals."

The intent of this document is just to serve as a guideline to make
code across an organisation "look" the same. Obviously none of these
guidelines will be important if you're coding a simple 200 line
application.

But when you are creating Large Scale C++ Software, it *does* help to
follow some sort of guideline (and the guidelines in this document seem
mostly reasonable to me). Think 20 years down the line.

hth,
-shez-

[Howard]

"John Dibling" <jd******@gmail.com> wrote in message
news:11**********************@g49g2000cwa.googlegr oups.com...

E. Robert Tisdale wrote:

I think that these guidelines are almost *all* wrong.

I agree, and here's one I particularly hate:

49. [snip] Note that structs are kept in C++ for compatibility with C
only,
and avoiding them increases the readability of the code by reducing the
number of constructs used. Use a class instead.

This implies that it's never correct to define a datatype that is just
a bag of bits, such as:

struct Name
{
std::string m_sFirst, m_sLast;
};

This implication is nonsensical and overly restrictive. The fact that
C++ gives the programmer many ways to accomplish a given task is a
*good* thing, not a bad thing. Everything must not necesarrily be a
full-fledged object.

What are you talking about? How is a struct not a "full-fledged object",
but "just a bag of bits"? The only differences between structs and classes
is the default visibility and default inheritance. The above sample is the
same as this:

class Name
{
public:
std::string m_sFirst, m_sLast;
};

I seem to recall that some early versions of C++ (such as Turbo C++, I
believe) defined struct and class differently, where a struct was just a
data holder (i.e., POD) and a class could include methods. But that is not
the case any more at all (and I don't know if it was ever the standard).

I see many people still using struct when all they want is a data holder. I
suspect that's for a few reasons. One, they used to do it that way, back
when their compiler required it. Two, they like the convenience of the
default public visibility for struct members (avoiding typing "public:"
every time). And three, it gives a quick visual clue that to them (and to
others who are used to this style) as to whether they're looking at an
object which simply holds some data, or one which has functionality of its
own.

But there's no requirement as to which you should use. You could use struct
everywhere and class nowhere, and as long as you specified the desired
inheritance and visibility, they'll accomplish the very same task.

One more thing: when you don't specify a constructor, destructor, etc. for
a struct or class, the compiler will generate a default one for you. So
really, even a "plain old struct" has *some* functionality.

My personal preference is to use struct only for POD data, and make
everything else a class. (Why? For the three reasons I gave earlier.)

Hmm... I guess that means I disagree with that rule, also. I just disagree
with your argument as to why struct should be kept. I want to keep it
because I like to use it, that's all. It's certainly not needed.

-Howard

[John Dibling]

Shezan Baig wrote:

The intent of this document is just to serve as a guideline to make
code across an organisation "look" the same. [snip] when you are
creating Large Scale C++ Software, it *does* help to follow some sort
of guideline (and the guidelines in this document seem
mostly reasonable to me). Think 20 years down the line.
I agree, coding guidelines are a good thing. But I believe that coding
guidelines should encourage programmers to generate better code, not
better *looking* code.

Here's an example. The guidelines state:
75. The if-else class of statements should have the following form:
if (condition) {
statements;
}

if (condition) {
statements;
}
else {
statements;
}

I see no benefit whatsoever from this recommendation, and don't think
that this kind of thing should appear in any coding guideline document,
even if it's just a "should." It simply can't help Joe Programmer to
write better code. The first if block is identical to:

if( condition )
{
statements;
}

....which is how I personally write such blocks. There's no difference!
In fact, if a coding guideline tells me I can't write my if blocks the
way I naturally do, I'll end up taking much longer to write code
becasue I'll have to correct what naturally falls out of my brain to
fit some pedantic mandate.

Moreover, a professional programmer should be expected to be able to
maintain other peoples' code just as easily as thier own, even if it
doesn't look like thier own, so long as the code isn't insanly
convoluted.

Instead of these sorts of style recommendations, I believe coding
guidelines should include things like:

"Prefer std::string to dynamically-allocated char buffers."

....or...

"Check all incoming pointer paraaters for validity before using them."

Take care,

John Dibling

[fuzzylollipop]

because .Name() != .Name(name)

one is a "getter" the other a "setter"

it is definately NOT good OO style to do it the way you are
recommending since everyone else has already agreed to do it the other
( more readable ) way.

[lilburne]

John Dibling wrote:

Shezan Baig wrote:

The intent of this document is just to serve as a guideline to make
code across an organisation "look" the same. [snip] when you are
creating Large Scale C++ Software, it *does* help to follow some sort
of guideline (and the guidelines in this document seem
mostly reasonable to me). Think 20 years down the line.

I agree, coding guidelines are a good thing. But I believe that coding
guidelines should encourage programmers to generate better code, not
better *looking* code.

Programmers read code more often than they write it. Were you to read a
book where the paragraphs were randomly formatted, or the typeface
changed from page to page because each typesetter had their own
preference, you'd be pissed off in no time.

Here's an example. The guidelines state:

75. The if-else class of statements should have the following form:
if (condition) {
statements;
}

if (condition) {
statements;
}
else {
statements;
}

I see no benefit whatsoever from this recommendation, and don't think
that this kind of thing should appear in any coding guideline document,
even if it's just a "should." It simply can't help Joe Programmer to
write better code. The first if block is identical to:

if( condition )
{
statements;
}

...which is how I personally write such blocks. There's no difference!
In fact, if a coding guideline tells me I can't write my if blocks the
way I naturally do, I'll end up taking much longer to write code
becasue I'll have to correct what naturally falls out of my brain to
fit some pedantic mandate.

Only for a short while within a couple of weeks the local style becomes
just as natural as your last local style.
Moreover, a professional programmer should be expected to be able to
maintain other peoples' code just as easily as thier own, even if it
doesn't look like thier own, so long as the code isn't insanly
convoluted.

Instead of these sorts of style recommendations, I believe coding
guidelines should include things like:

"Prefer std::string to dynamically-allocated char buffers."

...or...

"Check all incoming pointer paraaters for validity before using them."

The one doesn't preclude the other.

[John Dibling]

Howard wrote:

What are you talking about? How is a struct not a "full-fledged object",
but "just a bag of bits"?
[snip]
My personal preference is to use struct only for POD data, and make
everything else a class. (Why? For the three reasons I gave earlier.)

Hmm... I guess that means I disagree with that rule, also. I just disagree
with your argument as to why struct should be kept. I want to keep it
because I like to use it, that's all. It's certainly not needed.
Actually, I believe we agree (almost) completely, and that you didn't
see this is my fault. I use structs instead of classes for semantic
clarity only, to give a clue -- as you say -- as to how it is composed
and how it is used. I certianly agree that it isn't required.

As for what seperates a full-fledged object from just a bag of bits,
this gets in to a highly debatable area. What makes some data
structure an object is different according to almost every programmer.
I have never seen a defintion for the term "object" that I felt was
absolutely comprehensive and absolutely correct. I have a definition
that I use for myself, and you may have one that you use. According to
your definition,
struct/class Name
{
public:
std::string m_sFirst, m_sLast;
};

....might be an object, but according to my definition it is not. Your
definition might be just as valid as mine, and both definitions might
be practically useless in, er... practice.

Take care,

John Dibling

[Default User]

E. Robert Tisdale wrote:

C++ Programming Style Guidelines

http://geosoft.no/development/cppstyle.html

I think that these guidelines are almost *all* wrong.

An I think this is another attempt at a disruptive, off-topic thread by
the resident group troublemaker.


Brian

[Steven T. Hatton]

E. Robert Tisdale wrote:

C++ Programming Style Guidelines

http://geosoft.no/development/cppstyle.html

I think that these guidelines are almost *all* wrong.
For example:

11. Private class variables should have underscore suffix.
class SomeClass {
private:
int length_;
}

12. Generic variables should have the same name as their type.
void setTopic (Topic *topic)
// NOT: void setTopic (Topic *value)
// NOT: void setTopic (Topic *aTopic)
// NOT: void setTopic (Topic *x)

void connect (Database *database)
// NOT: void connect (Database *db)
// NOT: void connect (Database *oracleDB)

7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

There is one point Matthias Ettrich makes in this article that stands above
the others in importance. I wonder if anyone else will find that same
point as significant as I did. Any guesses as to what that point might be?

http://doc.trolltech.com/qq/qq13-apis.html

NB: The article does discuss Qt, and Qt's design specifically, but none of
the observations are exclusive to Qt, and each is as applicable to any
other API.
--
If our hypothesis is about anything and not about some one or more
particular things, then our deductions constitute mathematics. Thus
mathematics may be defined as the subject in which we never know what we
are talking about, nor whether what we are saying is true.-Bertrand Russell

[Rick N. Backer]

On Thu, 09 Jun 2005 10:59:37 GMT, "David Lee Conley"
<co********@earthlink.net> did courageously avow:

"E. Robert Tisdale" <E.**************@jpl.nasa.gov> wrote in message
news:d8**********@nntp1.jpl.nasa.gov...

C++ Programming Style Guidelines

http://geosoft.no/development/cppstyle.html

I think that these guidelines are almost *all* wrong.
For example:

11. Private class variables should have underscore suffix.
class SomeClass {
private:
int length_;
}

12. Generic variables should have the same name as their type.
void setTopic (Topic *topic)
// NOT: void setTopic (Topic *value)
// NOT: void setTopic (Topic *aTopic)
// NOT: void setTopic (Topic *x)

void connect (Database *database)
// NOT: void connect (Database *db)
// NOT: void connect (Database *oracleDB)

7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

I definitely don't agree with #7. I may be new to this, but I'm pretty sure
this violates one of the basic principles of OOD: polymorphism. Why use two
names for a function when you can overload it?

employee.Name(); matrix.Element(2, 4);
employee.Name(name); matrix.Element(2, 4, value);

Dave

It doesn't violate any guidelines that I'm aware of. As for your
example, if I am just perusing your code, I don't know what any of
those functions do by just looking at your functions calls.

These guidelines look like they might be a company's guidelines to
their developers and I don't really see anything wrong with them. We
need to understand that one of the reasons guidelines such as these
crop up is code maintenance. Code is easier to maintain among teams
of multiple developers if everyone is on the same wave length. That
way, anyone on the team can pick up anyone else's work and be able to
fathom it to the limits of their knowledge but should not run into
things they can't recognize right off. 'set' and 'get' have been
traditional prefixes for these kind of functions for a long time.

Ken Wilson

Amer. Dlx. Tele, Gary Moore LP, LP DC Classic w/P90s,
Jeff Beck Strat, Morgan OM Acoustic,
Rick 360/12, Std. Strat (MIM), Mesa 100 Nomad,
Mesa F-30

"Goodnight Austin, Texas, wherever you are."

[Rick N. Backer]

On Thu, 9 Jun 2005 14:26:45 +0100, "Fraser Ross"
<fraserATmembers.v21.co.unitedkingdom> did courageously avow:

"E. Robert Tisdale"

C++ Programming Style Guidelines

http://geosoft.no/development/cppstyle.html

I think that these guidelines are almost *all* wrong.
For example:

11. Private class variables should have underscore suffix.
class SomeClass {
private:
int length_;
}
It doesn't say why not to do this with all class members and I don't know a
reason.

It is one way, 10 pages down in the code, you can easily remember that
this is a private member variable and not just a local variable
when/if you see it in a function. Once again, it's all about ease of
maintenance.

7. The terms get/set must be used
where an attribute is accessed directly.
employee.getName(); matrix.getElement (2, 4);
employee.setName (name); matrix.setElement (2, 4, value);

The functions have different purposes so I agree with giving them different
names.

Fraser.

Ken Wilson

Amer. Dlx. Tele, Gary Moore LP, LP DC Classic w/P90s,
Jeff Beck Strat, Morgan OM Acoustic,
Rick 360/12, Std. Strat (MIM), Mesa 100 Nomad,
Mesa F-30

"Goodnight Austin, Texas, wherever you are."

[Stuart MacMartin]

All very interesting because it reflects my experiments over the years.

1. putting underscore at the end of variables

We use the MFC style of prepending with m_, e.g. m_name.
We all quickly came to like this one because:
- it's amply clear what's a class member and what's not
- there's no name conflict between a parameter name and a member name

2. Using other indications of type of variable

We rarely do this, and only when it clarifies the code.
The development environment tells us the type, and it's inconvenient
to have to change names when you change the type

3. Bracing style

The reason for:
if (something) {
blah
}

is to compress the lines a bit without risk that someone will insert a
trace or other bit of code and accidentally change the condition. Some
of us started doing this when exposed to I think Smalltalk, and others
when they saw code that was so sprawled with lines of braces that the
key lines of code were obscured. In my experience, people think one
way or another, and it's more productive in the long run and leads to
more maintainable code when the developer writing the software has some
latitude over formating. He's more likely to get the code right if he
isn't fighting a style that's unnatural to him -- like a jazz singer
trying barbershop or the other way around. (Eventually I've reverted
to the other format just because you can see the braces lined up
whereas trailing brace is often lost at the end of the line or hard to
distinguish from parentheses).

Note that insisting on braces when there is multi-line is to prevent
the silly mistake of either adding something to the braced context --
but the brace isn't there so the second line is no longer under the
"if" -- or the opposite, adding a line thinking it's outside the if ()
construct. Both happen occasionally, sometimes through keyboard
fumbling, and are really hard to track down. Systematic braces helps
avoid this.

4. "Now I write lots of code that goes against the standard"

Until I saw Java, I hated string GetName() const {return m_name;}
My feeling was this obscured the methods in the class.
Now I find, expecially with templates, that for many classes this is
easier, and clearer -- as user of a class I sometimes want to know if
it's intended to be fast or slow, or if the routine does what I think
it does.

I also find myself breaking some of the other rules I've followed over
the years.
e.g. I'll break an "if" onto another line occasionally without adding
the braces if it's clear and if I need to set a breakpoint.
But in all cases, it's a question of clarity, correctness and
maintainability. The guidelines are trying to encourage a style that
helps you write correct code (e.g. read the old Elemtel guidelines and
they explained the reasoning for everything). As my programming has
progressed I've manage to break some rules without losing sight of why
they were there in the first place.

Stuart