Reading great code

[gt8887b]

Hello!

In his recent newsletter embedded expert Jack Ganssle says that
programming students, as well as professional developers should readh
"great code" (hight quality/well-crafted code that works). He even
gives to examples. One is uC/OS-II operating system and the other is
TCP/IP stack for said system.


Do you know of other good examples of elegant and high-quality code
that is publicly available so that developers may look at it and learn?



It would be interesting to see it and may be even discuss why it is so
great.

 

[John Browning]

Hello!

In his recent newsletter embedded expert Jack Ganssle says that
programming students, as well as professional developers should readh
"great code" (hight quality/well-crafted code that works). He even
gives to examples. One is uC/OS-II operating system and the other is
TCP/IP stack for said system.


Do you know of other good examples of elegant and high-quality code
that is publicly available so that developers may look at it and learn?



It would be interesting to see it and may be even discuss why it is so
great.

Most programmers never reach the level where they're capable of writing
"great" code. How you even define "great" is debatable as there's a lot
of artistic license involved. It's not a hard science. However, those who
can consistently do it intrinsically understand how to convert program
requirements into beautiful code similar to the way a grandmaster at chess
intrinsically understands how to move his pieces around the board. It's a
combination of various mental "chunking" skills achieved after years of
practice (i.e., the ability to quickly and effortlessly see through a
problem without having to dwell on the constituent parts comprising that
problem). From this you can create an elegant solution without having to
think about it too much. It's hard to teach this to others however. You can
demonstrate a lot of sound principles but it takes tremendous practice and a
certain innate ability to master it yourself. Unfortunately, based on my own
experience, most people are incapable of it just like most can never become
a great chess player no matter how hard they try (even with Gary Kasparov as
your teacher). My own advice would be simple however. Make all your code as
generic and reusable (and robust) as possible. 95% or more of almost any
program can be made this way but 95% of all programmers don't understand
this fundamental rule. It's the hallmark of a great programmer however (if
you can master it you'll be on your way to writing "great" code - if you
want to take this offline I can send you some well documented C++ samples to
demonstrate).

 

[Rick Lones]

Hello!

In his recent newsletter embedded expert Jack Ganssle says that
programming students, as well as professional developers should readh
"great code" (hight quality/well-crafted code that works). He even
gives to examples. One is uC/OS-II operating system and the other is
TCP/IP stack for said system.


Do you know of other good examples of elegant and high-quality code
that is publicly available so that developers may look at it and learn?



It would be interesting to see it and may be even discuss why it is so
great.

It's old (1976) and it's Pascal, but . . .

For my money, the best programming technique book ever is "Algorithms + Data
Structures = Programs", by Wirth (ISBN 0-13-022418-9). Elegant algorithms,
artfully implemented, and he illustrates somewhat the process of creation
(including sometimes the messiness and false starts) rather than just presenting
finished programs which seem to come from thin air.

FWIW, I have used uC/OS-II and agree that it is excellent code as well - it has
that same quality of being "straight to the point". The author (Labrosse)
explains his code well in the accompanying book along with many useful OS concepts.

Regards,
-rick-

 

[Jon Skeet [C# MVP]]

My own advice would be simple however. Make all your code as
generic and reusable (and robust) as possible. 95% or more of almost any
program can be made this way but 95% of all programmers don't understand
this fundamental rule.

Robust I can agree with. Reusable less so - because in my experience,
the more reusable and generic you make it, the more complex it has to
be in order to accomplish the one task you have at hand. I often find
that I then never reuse the component in question, having gone to all
the trouble of making it reusable. These days, I build things in a less
reusable way until I can see that I've got code which *could* be reused
with a bit of a tweak. At that point with the appropriate unit tests in
place, it's usually not too hard to make the changes while keeping the
original use working.

If you know for sure that you actually need the code to be generic from
the start, that's a different matter of course.

This is often known as "YAGNI": "You Ain't Gonna Need It"

See http://c2.com/xp/YouArentGonnaNeedIt.html or
http://en.wikipedia.org/wiki/You_Ain't_Gonna_Need_It

 

[Peter Duniho]

Robust I can agree with. Reusable less so - because in my experience,
the more reusable and generic you make it, the more complex it has to
be in order to accomplish the one task you have at hand.

IMHO, this is only partially true.

In particular, one characteristic of a truly great programmer is to be able
to abstract a problem to the simplest form, which can often be a more
general, reusable solution rather than coding for some specific case.

It just depends on the problem, and I do agree that it's usually more
valuable to get something working first, and then improve, generalize, etc.
as needed. But IMHO some of the most elegant code also turns out to be some
of the most generic.

If the code, in being general, winds up with a bunch of special cases or
other extra conditional handling, then that's not what I'm talking about.
That's not an example of abstracting a problem...that's an example of
weighing down what ought to be simple code with a bunch of baggage. I'm
talking about seeing the forest for the trees and solving something in a
general way because that's the most efficient, least-complicate way to code
it.

It does happen.

As an added benefit to this approach, if one has truly abstracted a problem
to its simplest form, that often leads to the simplest implementation, which
has a direct effect on the robustness of the solution.

IMHO it's not an either/or thing. Sometimes it's better to solve the
problem in a very specific way, sometimes it's better to solve it in a more
general way. Part of the art of programming is knowing the difference.

Pete

 

[John Browning]

Robust I can agree with. Reusable less so - because in my experience,

the more reusable and generic you make it, the more complex it has to
be in order to accomplish the one task you have at hand. I often find
that I then never reuse the component in question, having gone to all
the trouble of making it reusable. These days, I build things in a less
reusable way until I can see that I've got code which *could* be reused
with a bit of a tweak. At that point with the appropriate unit tests in
place, it's usually not too hard to make the changes while keeping the
original use working.

If you know for sure that you actually need the code to be generic from
the start, that's a different matter of course.

This is often known as "YAGNI": "You Ain't Gonna Need It"

I couldn't disagree more The correlation between generic software and
successful software is simply overwhelming. When things are written
generically from the outset (and properly documented), you soon end up with
a large repository of stable and reusbable code. This is code that you and
your colleagues can become familiar and comfortable with and you can reuse
it over and over again across different projects. Every organization should
have a central library just like this (peer reviewed and properly
controlled). When things aren't done this way (almost always), I guarantee
that it's only a matter of time before you have very serious and expensive
problems on your hands (from code bloat to instability to serious
maintainance issues, etc.). Just about every software organization has these
problems in abundance because they don't follow this rule and I've witnessed
it first-hand over and over and over again (ad nauseam). It far more
expensive (and not just in $) by not doing things this way and it's the most
important thing I've learned after 24 years in the field.

 

[=?ISO-8859-1?Q?G=F6ran_Andersson?=]

Robust I can agree with. Reusable less so - because in my experience,
the more reusable and generic you make it, the more complex it has to
be in order to accomplish the one task you have at hand.

True. On the other hand, code that is supposed to be reusable is often
more robust than code that only seek to solve a specific problem. So
making code more reusable should make it more robust, even if the code
never actually will be reused.

This is of course unless, as you mentioned, making it more reusable also
adds too much complexity to the code.

To solve a part of a problem in a reusable way may also help you to make
the main part of a problem more streamlined, and make the special cases
fit into the standard model instead of adjusting the standard model for
every special case. So sometimes thinking in terms of reusability makes
the code less complex instead of more.

I often find
that I then never reuse the component in question, having gone to all
the trouble of making it reusable. These days, I build things in a less
reusable way until I can see that I've got code which *could* be reused
with a bit of a tweak. At that point with the appropriate unit tests in
place, it's usually not too hard to make the changes while keeping the
original use working.

I experience that too.

I also use that method sometimes to produce code that I know should be
reusable in the end. By first implementing the different cases with
specific code makes it easier to figure out the similarities between the
cases to see what should go into the reusable code.

 

[Peter Thornqvist]

Robust I can agree with. Reusable less so - because in my experience,

the more reusable and generic you make it, the more complex it has to
be in order to accomplish the one task you have at hand.

IME, this is not true unless you are trying to solve too many problems at
once. I've found that the best and most efficient way to implement something
is to first create a solution for the generic case (like a list class) and
then derive from that implementation for specific use (like a sorted list
class). This many times results in less complex and more robust code. The
amount of code might be larger compared to writing the specific
implementation directly, but that doesn't automatically indicate that the
code is more complex.

 

[Cor Ligthert [MVP]]

John,

Your word artistic did hit me, for that it is worth to read the book from
Ogilvy, nothing to do with developing however, in my idea should every
developer read that. It gives more knowledge to a developer than those
thousands of on technique based books it in my idea.

http://www.profitadvisors.com/ogilvy.shtml

He is writing as well about artists, those who he helps in his bureau direct
to find another job at his concurrent.

The job is in my idea to make hings maintainable, if you see discussions on
this dotNet boards between Jon and me it is mostly that Jon is more about
the artistic code and me about the maintainable code (although Jon wants as
well maintainable code is he in my idea staying an artist).

Therefore what is great code has always a point of view. Although I am in
fact as well an artist, and like to write very clever code where less
commands are used, is that in my idea good as hobby, not for real live.

Cor

 

[Kevin Spencer]

Well, if all this debate, each person making some excellent points, and
almost all at odds with one another over those very points, doesn't point up
the greatest difficulty of mastering programming, I don't know what will.

In fact, I view the whole thing as a balancing act. Elegant software is a
beautiful thing to behold, and just as rare. For one thing, it just takes
too long to write, and we developers are constrained by time and money
considerations. Reusability is also a double-edged sword, and although I
believe John and Jon are both correct, their conflict is more one of
emphasis than perhaps they realize.

The real trick is to master skills that enable one to stay more or less
within the limits of what *can* be achieved, and that perfection that any
conscientious programmer desires to achieve in his/her work. Every developer
finds his/her own unique methodology to strive towards that "golden mean,"
and each is unique because we all have a unique combination of gifts and
liabilities.

All that said, reading "good" code is always a good idea. As for "great"
code, it's hard to draw the line between the 2, and even reading "bad" code
can be a worthwhile process, as long as one is looking at it as "bad." One
can observe and learn from the pitfalls that others have fallen into, as
well as from the examples of those who have attained a measure of skill.

The most important aspect of a programmer's personal development is the
drive to become perfect, a goal which, although impossible to attain, is
worth aiming at. What you seek is what you get, in the long run. Aim for the
stars, and someday, you'll at least reach the moon.

--
HTH,

Kevin Spencer
Microsoft MVP
Chicken Salad Shooter
http://unclechutney.blogspot.com

A man, a plan, a canal, a palindrome that has.. oh, never mind.

I couldn't disagree more The correlation between generic software and
successful software is simply overwhelming. When things are written
generically from the outset (and properly documented), you soon end up
with

<snip>

 

[Ben Newsam]

Robust I can agree with. Reusable less so - because in my experience,
the more reusable and generic you make it, the more complex it has to
be in order to accomplish the one task you have at hand. I often find
that I then never reuse the component in question, having gone to all
the trouble of making it reusable. These days, I build things in a less
reusable way until I can see that I've got code which *could* be reused
with a bit of a tweak. At that point with the appropriate unit tests in
place, it's usually not too hard to make the changes while keeping the
original use working.

If you know for sure that you actually need the code to be generic from
the start, that's a different matter of course.

I agree with this 100%. The general is much harder to write than the
specific.

 

[Peter Thornqvist]

Well said

 

[Peter Thornqvist]

I agree with this 100%. The general is much harder to write than the

specific.

Not all code can (or should) be generalized. Only when it is apparent that a
generalization is of use and (at least somewhat) easy to accomplish, should
that path be considered. I believe that when it is hard to write a general
implementation, it is an indication that you should probably not even try.
OTOH, if a generalization "falls in your lap", it is often easier to write
than specializing directly.

Finding solutions to programming problems is a lot about "seeing it". Even
if you understand the requirements on a basic level, it isn't until you get
that "I know how to solve this" feeling that you truly know if the solution
lends itself to generalization. It is, as much in live, depending on the
situation.

I have been in the situation many times where I have written a specialized
implementation and several days, weeks or even months later realized that it
could be generalized for other use and subsequently rewritten the code.
Programming (to me) is an iterative and evolutionary process where I
commonly return to old code several times to tweak, rewrite and optimize.
Hopefully this results in great (or at least good) code at some point. The
trick is to know when enough is enough

 

[=?ISO-8859-1?Q?G=F6ran_Andersson?=]

The general is much harder to write than the specific.

Often true, but not always because you get less code for more work.
Sometimes it's mostly because the generalized code that you get is far
superior to the specialized code. You can end up with code that is more
efficient and more maintainable because it's simpler and more elegant.

 

[=?ISO-8859-1?Q?G=F6ran_Andersson?=]

Therefore what is great code has always a point of view. Although I am in
fact as well an artist, and like to write very clever code where less
commands are used, is that in my idea good as hobby, not for real live.

I agree fully. I think that it's very good for a programmer to write
extreme code as a hobby. Size optimizing assembler code or writing
clever one-liners is something that you rarely do in production code.

Experimenting with code should mostly be done for it's own sake, and not
when you are supposed to whip up some decent, stable, working code for
some moderately difficult task.

What you learn from experimenting with code will show up in the
production code anyway, as knowledge and elegant solutions, not as
clever and tricky ways of using things in a way they werent really ment
to be used.

 

[Registered User]

Hello!

In his recent newsletter embedded expert Jack Ganssle says that
programming students, as well as professional developers should readh
"great code" (hight quality/well-crafted code that works). He even
gives to examples. One is uC/OS-II operating system and the other is
TCP/IP stack for said system.

Do you know of other good examples of elegant and high-quality code
that is publicly available so that developers may look at it and learn?

It would be interesting to see it and may be even discuss why it is so
great.

The key to writing elegant code is to start with a well considered
design.

regards
A.G.

 

[Registered User]

Experimenting with code should mostly be done for it's own sake, and not
when you are supposed to whip up some decent, stable, working code for
some moderately difficult task.

What you learn from experimenting with code will show up in the
production code anyway, as knowledge and elegant solutions, not as
clever and tricky ways of using things in a way they werent really ment
to be used.

This is absolutely correct as it describes part of the design process.
Any code written during the design process is strictly throw-away
material written for clarification of concept. In contrast a
programmer's code is often considered "too valuable" to discard.

regards
A.G.

 

[Jon Skeet [C# MVP]]

Often true, but not always because you get less code for more work.
Sometimes it's mostly because the generalized code that you get is far
superior to the specialized code. You can end up with code that is more
efficient and more maintainable because it's simpler and more elegant.

That's true - *if* you use the general functionality. It is usually
harder to understand the general functionality than specific
functionality. That's fine if you actually use it - but if you're only
ever going to use the code in one particular way, there's not a lot of
point in making it hugely flexible.

Of course, when you then find yourself doing something similar,
*that's* the time to refactor the previous code and build the more
general functionality.

 

[Jon Skeet [C# MVP]]

This is absolutely correct as it describes part of the design process.
Any code written during the design process is strictly throw-away
material written for clarification of concept. In contrast a
programmer's code is often considered "too valuable" to discard.

That assumes a design process which comes strictly ahead of the real
code. With TDD, although you need the high level architecture ahead of
time, the design of the public contract often emerges as you try to
write tests which use the production class in the easiest way. Guessing
exactly what will be easy to use ahead of time is often very hard
indeed - and a waste of time, IMO, when writing tests can get you to
the end result faster, and with demonstrably working code.

 

[John Browning]

In fact, I view the whole thing as a balancing act. Elegant software is a

beautiful thing to behold, and just as rare. For one thing, it just takes
too long to write, and we developers are constrained by time and money
considerations. Reusability is also a double-edged sword, and although I
believe John and Jon are both correct, their conflict is more one of
emphasis than perhaps they realize.

Yes, it definitely is a balancing act. However, the "constrained by time and
money" argument is one I've heard far too many times over the years. In
practice it doesn't wash however because one is always restrained by
resources in every endeavour in life. The goal is not to achieve Utopian
perfection which clearly isn't possible (or even definable), but to strive
for reusablity as best as you can given your limited resources. When you
look at almost any software however, what you see is not code that was
restrained by resource limitations, but code that's indicative of people who
are just bad at what they do. Their code wouldn't improve much if you gave
them all the time and money in the world to work with (within reason of
course). OTOH, in the hands of someone who does know what they're doing
(rare as that might be), the same code will be reasonably clean and generic
even with the very same constraints in place (in spite of the naysayers who
claim this can't be done - it certainly can be). And why is that? Because
they understand that program correctness is incredibly difficult to achieve
otherwise. That by not doing things this way from the outset, all the
negative fallout associated with most software will soon manifest itself.
You therefore have it it backwards. The time and money issues only rear
their ugly heads in the aftermath of a poorly written program (and in fact
are primarily caused by it), not during its initial creation.