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.getNam e(); matrix.getEleme nt (2, 4);
employee.setNam e (name); matrix.setEleme nt (2, 4, value);

[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.getNam e(); matrix.getEleme nt (2, 4);
employee.setNam e (name); matrix.setEleme nt (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********@ear thlink.net> did courageously avow:

"E. Robert Tisdale" <E.************ **@jpl.nasa.gov > wrote in message
news:d8******* ***@nntp1.jpl.n asa.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.getNam e(); matrix.getEleme nt (2, 4);
employee.setNam e (name); matrix.setEleme nt (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"
<fraserATmember s.v21.co.united kingdom> 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.getNam e(); matrix.getEleme nt (2, 4);
employee.setNam e (name); matrix.setEleme nt (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