Example of good C++ design/code

[SW]

I don't think you can set an absolute maximum limit, as there
are special cases. (Consider a function which consists of a
single switch statement, with a 100 or so cases.) But in
general, anything over about 10 lines in a function should raise
eyebrows; well written functions are *usually* fairly short. (I
did some statistics on my code once, and found that the average
function length was around 7 lines. I'm not too sure how
significant that is, however, since I'm pretty sure that the
variance is important.)

I agree that functions should be short and concise. I think that it is
also important to write deterministic functions as often as possible. It
can make reasoning a lot easier.

SW

 

[James Kanze]

Where do you get this figure of 10 lines from? Seems like
another arbitrary number just like 50 to me.

Of course it's arbitrary. It's the most frequently cited value,
and it seems to be more or less valid in most of the application
domains where I've worked, but the real measure of importance is
cyclomatic complexity, not lines or statements. A 50 line
program without a single if or loop is probably not a problem;
the cyclomatic complexity is only 1. At least in the
application domains where I've worked, however, there's just
never a reason for alining 50 statements one after the other,
with no conditions. Often, even 10 is a lot.

Note too what I said about variance: the average length will
often be very low because the code contains a lot of one line
accessor functions. (Such functions also lower the average
cyclomatic complexity, since they have very low cyclomatic
complexity as well.)

Still, for most application domains (and with some notable
exceptions where switches are involved), 50 lines should raise a
red flag.

 

[James Kanze]

This comment brought a smile to my face. Back in 1998, on my
first day of my first programming job, one of the lead
programmers came up to the chief designer, while the later was
showing me around, and started talking about a new class that
he felt was needed in the company's proprietary framework. I
was pretty nervous and worried that I wouldn't be able to hold
my own in my new workplace, what if I don't know enough or
have to keep looking things up and thus look bad? Then I
realized that what the lead programmer was asking for was
std::list... "Why don't you just use std::list?" They looked
at me with curious faces, "what's that?"

What would you expect? The standard itself was only adopted in
1998, and implementations didn't follow immediately. In 1998,
there were very few compilers which supported std::list (and
even fewer which did so in a way compatible with the standard).

 

[rabbits77]

I agree that functions should be short and concise. I think that it is

also important to write deterministic functions as often as possible. It
can make reasoning a lot easier.

What is a "deterministic function". Surely you don't
mean the opposite of a "stochastic function" since
that doesn't make much sense but the only sense
I can think of the word "deterministic" is that one.
Could you please clarify?

 

[Brian]

What would you expect?  The standard itself was only adopted in
1998, and implementations didn't follow immediately.  In 1998,
there were very few compilers which supported std::list (and
even fewer which did so in a way compatible with the standard).

I was working as a contractor in 1998 and was expected
to use Roguewave classes. At that time I felt the
company was a little bit behind the times and fought
for being able to use the STL. After a couple months
of clashes, they allowed people to use the STL if they
wanted.


Brian Wood
http://webEbenezer.net
(651) 251-9384

 

[Miles Bader]

I've read that if you need comments at all you're doing something
wrong.

That's just idiotic. Maybe the people who say that have only ever
done extremely simple tasks where they can get away with such
simplistic dogma, but in the real world, there's _tons_ of "auxiliary"
information that goes into writing code that's not directly part of
the algorithm or data, but is important for anybody trying to
understand it. [e.g., "This code uses algorithm X because Y. It's
important to maintain invariant Z because Q."]

Of course even for simply understanding the algorithm, comments are
very useful, because they can summarize and emphasize what the code
does in a way that really eases the task of somebody reading
unfamiliar code.

-Miles

 

[Miles Bader]

But there's the odd one that has to carry out a _load_ of functionality
all in a row, and there are no real places in the function where it
should be chopped up. So we don't bother - until one day half the
functionality needs to be shared with something else, then it gets
chopped at that point.

Indeed.

Splitting up such code usually entails creating new abstractions,
especially if there's local state. What's then required is a judgement
whether the thus-abstracted code is actually easier or harder to
understand/maintain than the straightforward-but-lengthy code.

["Abstractions" which aren't entirely natural but merely created for the
purpose of splitting stuff up may well be more awkward and less clear
than the non-abstracted code.]

I guess the main point is that such situations should be judged on the
end goals, e.g. readability and maintainability. Simplistic rules like
"no function longer than N lines" are often useful rules of thumb for
achieving such goals, but they _are not the goal themselves_, and
shouldn't be treated as such.

-Miles

 

[SW]

What is a "deterministic function". Surely you don't
mean the opposite of a "stochastic function" since
that doesn't make much sense but the only sense
I can think of the word "deterministic" is that one.
Could you please clarify?

Deterministic function is a function which gives the same result for the
same arguments given to it. It somewhat implies that the function does
not depend on variables outside of itself.

SW

 

[Stefan Ram]

Agree, 10, 50, 100 lines are all artificial limits and any such limits

It turns out that jump instructions, like »goto«, »break«,
or »return« can make code more difficult to analyze
especially in /large/ blocks (functions).

Using »break« or multiple »return«s in a small function does
not make reading so much more difficult. So, for small
functions the criticism of (intra-functional) jump
statements does not apply in the same intensity as for
larger scopes.

When one uses one function for each conceptual operation,
functions often turn out to be small. I would not mind a
very large function given the case, that there is no
reasonable way to subdivide it any more (that is, it already
has high cohesion). But this just happen to occur rarely.

 

[cpp4ever]

I was just wondering what the erudite folks reading this group would
recommend as an example of a clean, well designed and coded C++
application. I'm particularly interested in the way classes are
composed, and I'm also fairly interested in exception handling. All C+
+ books are full of examples of cars and cats but these seem to be
idealized examples, and I'm interested in real work examples. Perhaps
there are some open source projects which are readily obtainable which
someone here can give me a pointer to.

Yikes, what a hullabaloo this has created. I hope you find what works
for you, but always bear in mind that others may have to look at your
code at a later date. Generally if the code is clean, well designed,
documented, and using a reasonable coding style, it should be easier to
maintain and develop in future. Restarting from scratch is an expensive
option whose is expensive, and is usually under estimated.

JB

 

[Jorgen Grahn]

I was just wondering what the erudite folks reading this group would
recommend as an example of a clean, well designed and coded C++
application. I'm particularly interested in the way classes are
composed, and I'm also fairly interested in exception handling. All C+
+ books are full of examples of cars and cats but these seem to be
idealized examples, and I'm interested in real work examples. Perhaps
there are some open source projects which are readily obtainable which
someone here can give me a pointer to.

You got a lot of replies. Most didn't answer your question.

Those that did generally pointed out libraries. A word of warning
there: libraries are a bit odd. They have to be flexible where normal
code can be single purpose; they have to have detailed API
documentation whereas with normal code, everybody who has to care can
simply read it. And so on.

IMHO, too much C++ code is too general and abstract as it is, so
please don't design your code as if it was a reusable library.

A real answer? Sorry, no. 'groff' is C++, but very old. The 'lftp'
FTP client: maybe. I haven't looked at it.

I've been doing C++ for something like ten years, and haven't seen any
good code I can recommend. I haven't really looked, though. I
probably should have.

/Jorgen

 

[Poldie]

You got a lot of replies. Most didn't answer your question.

LOL! You noticed too!

IMHO, too much C++ code is too general and abstract as it is, so
please don't design your code as if it was a reusable library.

A real answer?  Sorry, no. 'groff' is C++, but very old.  The 'lftp'
FTP client: maybe. I haven't looked at it.

Eh...if you're not looked at it, why are you suggesting it?

I've been doing C++ for something like ten years, and haven't seen any
good code I can recommend.  I haven't really looked, though.  I
probably should have.

It's funny - you'd after hundreds of forests have been turned into
books about OO design, patterns, paradigms, good practice etc etc
there'd be a few apps which take advantage of all that which
interested parties can take a look at, but they're proving hard to
find if they exist at all.

 

[Jorgen Grahn]

....


Eh...if you're not looked at it, why are you suggesting it?

I'm not -- I said 'maybe'. It's just one of the very few free software
projects in C++ that I know of and have used, as an end-user.

It's funny - you'd after hundreds of forests have been turned into
books about OO design, patterns, paradigms, good practice etc etc
there'd be a few apps which take advantage of all that which
interested parties can take a look at, but they're proving hard to
find if they exist at all.

It *is* strange. On the other hand, I can't say I know a lot of good
C code out there either.

And perhaps we're not looking hard enough. I sure am not.

/Jorgen

 

[JustBoo]

I was just wondering what the erudite folks reading this group would
recommend as an example of a clean, well designed and coded C++
application.

www.ogre3d.org
http://www.ogre3d.org/download/source

HTH