Any "Pretty" Code Out There?

andhow writes "Practically any time I hear a large software system discussed I hear "X is a #%@!in mess," or "Y is unmanageable and really should be rewritten." Some of this I know is just fresh programmers seeing their first big hunk o' code and having the natural reaction. In other cases I've heard it from main developers, so I'll take their word for it. Over time, it paints a bleak picture, and I'd be really like to know of a counterexample. Getting to know a piece of software well enough to ascertain its quality takes a long time, so I submit to the experience of the readership: what projects have you worked on which you felt had admirable code, both high-level architecture and in-the-trenches implementation? In particular I am interested in large user applications using modern C++ libraries and techniques like exception handling and RAII."

Firefox

Just kidding :))

Re:Firefox

IMHO, postfix takes the cake for the most elegant and readable code I've ever looked at. At one point I found an screenshot of qmail vs. postfix code in similar areas for handling some condition. The qmail code was hardcoded, had nasty loops and was just plain unbearable. The postfix version, however, was exceedingly elegant and I knew right away what the code was doing.

I only wish firefox was 10% as elegant and cruft free as postfix.

Re:Firefox

At one point I found an screenshot of qmail vs. postfix code in similar areas for handling some condition. The qmail code was hardcoded, had nasty loops and was just plain unbearable. The postfix version, however, was exceedingly elegant and I knew right away what the code was doing.

And don't forget that postfix is well-commented, and with superb documentation. Re the comments about qmail, I've kept lying around in my mailbox Linus' thoughts about qmail. Couple of interesting points in there.

On Sun, 6 Jun 2004, Kalin KOZHUHAROV wrote:

Well, not exactly sure about my reply, but let me try.

The other day I was debugging some config problems with my qmail instalation and I ended up doing:
# strace -p 4563 -f -F
[...] (deleted to bypass lameness filter)
qmail is a piece of crap. The source code is completely unreadable, and it
seems to think that "getpid()" is a good source of random data. Don't ask
me why.

It literally does things like

        random = now() + (getpid() (two less than signs deleted) 16);
and since there isn't a single comment in the whole source tree, it's
pointless to wonder why. (In case you wonder, "now()" just does a
"time(NULL)" call - whee.).

I don't understand why people bother with it. It's not like Dan Bernstein
is so charming that it makes up for the deficiencies of his programs.

But no, even despite the strange usage, this isn't a performance issue.
qmail will call "getpid()" a few tens of times per connection because of
the wonderful quality of randomness it provides, or something.

This is another gem you find when grepping for "getpid()" in qmail, and
apparently the source of most of them:

        if (now() - when (less than sign deleted) ((60 + (getpid() & 31)) (two less than signs deleted) 6))

Don't you love it how timeouts etc seem to be based on random values that
are calculated off the lower 5 bits of the process ID? And don't you find
the above (totally uncommented) line just a thing of beauty and clarity?

Yeah.

Anyway, you did find something that used more than a handful of getpid()
calls, but no, it doesn't qualify as performance-critical, and even
despite it's peyote-induced (or hey, some people are just crazy on their
own) getpid() usage, it's not a reason to have a buggy glibc.

                Linus

Re:Firefox

I've personally suffered greatly from a far worse, but similar usage of a sequentially assigned number, when a random number was called for. At Berkeley, as an undergrad, many classes I needed were over-full. The stupid COBAL programmer Berkeley hired to do student-class assignments needed a random number too break ties. He took the last digits of the student ID, and students with a higher number got in, and the students with lower were kicked out (mine ended in zeros). One semester, I applied for 20 units, and only got assigned 3, but the 3 were given to a prof so horrible I immediately dropped the class.

There's an interesting story about the difference between a Berkeley trained engineer and a Stanford trained engineer. The Stanford engineers typically finish college, and are downright shocked when they enter Dilbert Land, and for a while are unable to perform well. Berkeley grads don't seem to notice the transition, and get right to work.

Re:Firefox

Are there any operating systems out there that use random numbering of PIDs?

OpenBSD randomly numbers PIDs. Malloc and mmap on OpenBSD map pages into a random part of the process's address space too. A lot of work has been done to ensure that an attacker knows as little as possible about a program that they manage to compromise as possible.

For low-grade random numbers use something like /dev/urandom (on UNIX) instead. For high-grade random numbers, use /dev/random and note it may take a while to build the entropy.

By 'UNIX' you mean 'Linux.' Other *NIX platforms do not always provide two entropy sources. On OpenBSD, /dev/random is a hardware random number generator, srandom is the strong (blocking if not enough entropy is available) random number generator, urandom is the one which transparently degrades the randomness if entropy is not available, prandom is a simple psuedo-random number generator and arandom is a device for producing seeds for an ARC4 random number generator. On FreeBSD, there is just /dev/random, which is the Yarrow generator seeded periodically from the various entropy sources.

Don't ever hard-code /dev/* into your program unless it's one of the devices specified by POSIX [opengroup.org]. Last time I checked, this limited it to /dev/null, /dev/console and /dev/tty.

Re:Comments lie. Code never lies.

Only because DJB won't honor it. [jcb-sc.com] People have found bugs in his code, but he refuses to acknowlege them.

As my page (to which you link) notes, these bugs are likely exploitable only in theory.

And I've been hired (and paid well) to modify qmail code, including patching it to fix bugs as well as extending it, for years now, but nobody has even inquired as to what it'd take to fix the "Guninski" bugs that might theoretically be exploitable — at least, not so far.

I think that's a pretty sure indication that the qmail user base does not consider those bugs to be sufficiently worrisome to fix. (I did publish a simple fix to one of the first bugs Guninski found; that fix was incorporated into netqmail. But I did that gratis.)

I don't know offhand whether DJB has ever acknowledged any bugs in qmail. But, just as code doesn't lie while comments can, code that is reasonably well-specified, as qmail's components' interfaces are, cannot pretend bugs don't exist in it, even if authors or fanboys do, just as it can't pretend it has bugs even when claimed otherwise[*]. So I don't particularly miss djb's opinions and pronouncements on such issues, since I can read the code and decide for myself.

[*] There's a web page out there that claims "qmail-smtpd does not detect CR LF properly on packet boundaries", which strikes me as complete and utter — as well as easily demonstrable, by simply looking at the code — nonsense. Not that it can't happen, but it'd almost certainly be due to an OS, networking, or (non-qmail) library bug. Tellingly, despite the high likelihood such a bug would result in huge numbers of legitimate emails being rejected by many qmail servers worldwide, there's no information on this alleged bug beyond somebody supposedly reporting it. That's only marginally more persuasive than saying "qmail-smtpd dropped every third email on every server running it on March 17, 2001, between 11:45 and 12:15 UTC, according to a guy I overheard in a bar the other day." Color me unimpressed.

Re:Comments lie. Code never lies.

I'll comment (inline) as someone who has come to appreciate certain of qmail's strengths even while tolerating (to varying degrees) its weaknesses:

I thought it was hideous. From memory (it has been awhile):

• Hard coded file and folder names (it must be in exactly one location, too bad if you have a need for two outgoing SMTP servers running on the same box with different configurations)

That's annoying, but basically a security feature — you can be reasonably assured that a given qmail executable, especially qmail-queue (which is the only setuid-root program in qmail), is hard-coded to operate on only certain directories (aka folders) and files. And it's not "too bad" if you need to run a second SMTP server; just configure, build, and install as many distinct qmails as you need, with the configuration files (such as conf-qmail, normally /var/qmail) set as you want them. But I think it could be more flexible without sacrificing security assurances.

• Strange homegrown replacement for the standard C library

I gather djb's perception of the situation (at the time he wrote qmail and related software) was such that he'd substitute "Secure" for "Strange" above, but I don't personally know of exploitable bugs in contemporary C libraries, so I can't vouch for that. However, exploitable bugs in C code that uses standard C libraries are well-known, which is another reason I believe he grew his own C library.

• Memory deallocation done by exiting the program

Definite win for security and speed, if you don't have memory-leak problems as a result (and I don't think any qmail component does, modulo known issues with requiring per-process VM limits on Internet-facing components such as qmail-smtpd). As soon as your program starts down the path of calling free(), or, hey, even malloc(), if it can reasonably avoid them, it gets much more complicated and bug-prone, something you don't want in a system as crucial to have working correctly with no exploitable bugs as an email server.

• Odd preprocessor "template" functions

Haven't studied this enough to quite "get" what he was trying to accomplish vs. other approaches that could have been used, but they are doggone annoying to deal with at times.

• A seeming hatred of descriptive variable or function names

Agreed.

I don't have fond memories of the experience.

qmail code is pretty ugly when looked at closely enough, and can seem unnecessarily "different" from a more-distant perspective.

However, pull back far enough and look at it, and you might be able to appreciate that it is, in its own way, a work of art: a reliable, secure, powerful email system — just as pretty much any sufficiently large and beautiful work of art can look pretty flawed when scrutinized closely, especially without an awareness of the "big picture".

So if I wanted to play around with an email server and make it do all sorts of slick stuff, I wouldn't pick qmail.

But if I wanted to improve a mail server in some fashion while still being reasonably assured the resulting (modified) system wouldn't have remotely exploitable bugs in

in the distance...

I can almost hear the FOSS trolls approach...

sure

Hello World!!!

Re:sure

And yet, according to some poor paranoid soul, still contains multiple security flaws. I'll wait for the proof-of-concept before starting to worry. Or update to the English 2.0 "'sup, bitches?!" version.

Hello World

public interface MessageStrategy {
        public void sendMessage();
}

public abstract class AbstractStrategyFactory {
        public abstract MessageStrategy createStrategy(MessageBody mb);
}

public class MessageBody {
        Object payload;
        public Object getPayload() { return payload; }
        public void configure(Object obj) { payload = obj; }
        public void send(MessageStrategy ms) {
                ms.sendMessage();
        }
}

public class DefaultFactory extends AbstractStrategyFactory {
        private DefaultFactory() {}
        static DefaultFactory instance;
        public static AbstractStrategyFactory getInstance() {
                if (null==instance) instance = new DefaultFactory();
                return instance;
        }
        public MessageStrategy createStrategy(final MessageBody mb) {
                return new MessageStrategy() {
                        MessageBody body = mb;
                        public void sendMessage() {
                                Object obj = body.getPayload();
                                System.out.println(obj.toString());
                        }
                };
        }
}
public class HelloWorld {
            public static void main(String[] args) {
                        MessageBody mb = new MessageBody();
                        mb.configure("Hello World!");
                        AbstractStrategyFactory asf = DefaultFactory.getInstance();
                        MessageStrategy strategy = asf.createStrategy(mb);
                        mb.send(strategy);
            }
}

license

Ooops, I almost forgot:
/*
      Hello World
      Copyright 2002 MillionthMonkey

      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at

              http://www.apache.org/licenses/LICENSE-2.0 [apache.org]

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
*/


You're welcome, "World"!

Re:Hello World

This is such an exquisite example of design pattern overkill that I may require a private moment.

Re:Hello World

This is such an exquisite example of design pattern overkill that I may require a private moment.

It is the Gang-of-four Job_Security_Strategy pattern. Only the author can figure out their own code like this, and if you get paid per volume of code, you get wealthy.

     

Re:Hello World

Not so secure when the company is sued for stealing source code. He took credit (with his copywright notice) for a very old joke. A blatent copy-and-paste. One has to wonder how much of that he does on the job.

Ha ha, joke's on you, you dick- that "old joke" was written by me five years ago [slashdot.org] as part of a larger post and I was not at work- in fact it was way after hours and I was about to go home. I just started with the base concrete implementation and this is what it looked like after a few minutes of stuffing patterns into it- Singleton, Factory, and Strategy. I keep thinking one of these days I'll release a 2.0 version with Proxy and Bridge. Since I was the original author I retain the right to paste it wherever I want and to attach any license agreement I feel like attaching.

This has become the most famous code I've ever written which is the sort of thing that makes you reflect on your career. So far it has netted me about 20-30 karma points over the years (lord knows how much karma was gotten from pirated copies). I found it being examined in some software engineering papers and it even made its way into one of the patterns books [powells.com] (as an example of "Patterns Happy" code). When I found out about that, I made the guy send me a free copy and acknowledge me in print so I can maybe net some jobs unnecessarily screwing up simple code with GoF patterns which always pays well. Now that I released it under the terms of the Apache license he might come back for his book.

Re:Hello World

I just read your original post.

You're officially my hero.

Re:Hello World

/** Look, ma, no literals */
public class Hello_World {
  public static void main(String ... args) {
    System.out.println(Hello_World.class.getSimpleName ());
  }
}

Hello World (Newer Version)

I spent about an hour on this, but I think it's funny. There was no way to get this past the lameness filter, so I used nopaste: http://rafb.net/p/D1f39951.html [rafb.net]
Here is a little teaser though :)

/**
* This program is an elaborate joke about the strucuture of the Java
* programming language. Technically you'll have to put all the
* public interfaces and classes in their own file to get it to
* compile. The actual code came from a slashdot post, comments were
* later added by ookabooka.
*
* Originally Copyright 2002 MillionthMonkey.
*
* Ridiculously verbose and mostly useless comments (AKA good
* commenting) added by ookabooka Copyright 2007.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
* http://www.apache.org/licenses/LICENSE-2.0
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an "AS IS"
* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing
* permissions and limitations under the License.
*
* TODO:
* Add some try/catches and a plethora of exceptions to further insult
* Java.
*
* @author ookabooka
* @version 2.41.54b_2-rc4
* @see http://ask.slashdot.org/article.pl?sid=07/07/14/20 11208
*/

Re:Hello World (Newer Version)

Wow! That's impressive- I feel guilty now for carving so many minutes out of someone's life. Although if there were javadocs, I'd imagine that most of these disparaging comments would be within the HelloWorld class itself. The library code javadocs should always have lofty descriptions of themselves as if they're going to do brain surgery. Especially if they have empty implementations.

If I wrote this code in 2007 I would have used "setPayload()" instead of "configure()" so that MessageBody would follow standard JavaBean conventions. That would let me easily wire one up in a Spring XML file. Maybe I could even insert AOP pointcuts somewhere. After all Hello World is the sort of application that practically screams for aspect oriented programming.

Re:Hello World (Newer Version)

Oh I throughly concur. We should set up a sourceforge project to get the community involved. There are a lot of aspects of the Java language that simply aren't being utilized. Check out this program I made a few months ago. It contains every Java keyword and is (nearly) impossible to follow the logic. Again due to the lameness of the lameness filter you'll have to go to http://rafb.net/p/g46jLN20.html [rafb.net] to see it in all its correctly-indented and colored glory, but here it is:

public strictfp class Semantics extends Exception {
private static volatile transient boolean l = false;
private transient volatile static short j = 1;
public volatile static transient Exception LogicClass = new Semantics();
protected strictfp synchronized boolean WTF() throws Exception {
again: do {
l = !l;
without: try {
assert l ? true : LogicClass instanceof Semantics;
continue;
} catch (AssertionError e) {
j++;
LogicClass = new Exception();
break again;
} finally {
switch (j % 2) {
case 0:
LogicClass = this;
break again;
default:
break without;
}
}
} while (--j > -10 ? false : true);
throw this;
}
public static void main(String[] args) {
Semantics s = new Semantics();
try {
System.out.println(s.WTF());
} catch (Exception e) {
System.out.print(s.l);
}
}
}

New Law?

The cruftiness of source code is directly proportional to the amount of time spent working on it times the number of people working on it.

Has someone created such a law before?

Re:New Law?

The cruftiness of source code is directly proportional to the amount of time spent working on it times the number of people working on it.

I think you meant the cruftiness of source code is direcly proportional to the number of people working on it DIVIDED BY the amount of time spent working on it.

This explains why commercial source code produced by large teams of programmers under tight arbitrary deadlines tends to be sloppy. Source code produced by passionate hobbyists under the "we'll release it when it's done" deadline perspective tends to be cleaner.

Re:New Law?

Cruftiness is the quality of having cruft. Cruft is the stuff that accumulates on code over time. Cruft has no odor, but it stinks. Cruft has no mass, but it weighs the code down. Cruft can't be seen, but it's ugly. Cruft cannot be young, it's always old. Cruft can't be deliberately added, it only appears when you're not looking. Cruft can't be explained to managers, except through awkward car analogies. They still won't get it because managers drive well-maintained elegant foreign cars like BMW's, which gather no cruft. Programmers understand, because their Fords and Chevys are practically built of cruft. Harley motorcycles should have cruft, but noise dissipates cruft. Cruft is mysterious.

Cruft is never present on code which hasn't had enough work. Cruft only appears on code which has been worked too long, by too many people.

Re:New Law?

No, submit it to foldoc.org. Also, it needs a corollary, which we'll call The Hobo Tangent: Enhancements are the root of all evil.

Let's cue the scene...

An application's code is written by a competent developer and is nice and clean and pretty. He releases the application, and its a success. He gets moved to the next high profile project, and then the application's code gets handed to the maintenance droid, you know, the new guy on the team who shops *exclusively* at Whole Foods, listens to Nickelback, and has stacks of People magazine in his cubicle. He took a semester of VB while at Party U pursuing a liberal arts degree, and so he is a programmer too, you know!

Then, some PM or business manager who probably gets paid more than the original competent developer gets some bright ideas to make the application do things it never was intended to do. Let's say its a scheduling tool. Well, hey, they say, let's make it ALSO have an RSS feed! And a document repository! And a calculator! Can can you create some little project management software to work with it? A requirements document gets written, and a timeline is assigned.

Everyone does their little piece, totally oblivious to the steaming pile of dung spaghetti they are turning the application's code into.

Two years later, the original developer gets called to fix a problem that is simply beyond the dimwits holding the code. Poor guy doesn't even recognize his own application, and for him, it's like getting called to the morgue to ID the remains of a family member.

And that, friends, is why people complain about bad code.

Does this post make me sound cynical?

Amarok?

I'm just a 15 year old with a basic knowledge of C++, I've cracked open some source packages to test how much I know from time to time and Amarok seemed fairly well done to me, though that is of course compared to other packages, I still hyad to do a little bit of searching around to understand it.

Also the Last.fm player seems fairly well done, though for both these programs I didn't look through the full code or change anything, so maybe I just happened to stumble across the only 2-3 human-readable source files?

Re:Next up on slashdot...

I couldn't agree more. As I grow older, I've learned there really is a time when something is "good enough" to satisfy known requirements. I find that many applications are over engineered to some pie in the sky version of what's right and good - usually at the expense of simplicity and stability. I've often heard Java folks talk about re-factoring code and that's fine if no one is using your app, but in the event that folks and money are dependent on it, then re-factoring really just increases risk to all involved. The best possible outcome is that no one will notice the changes.

It's definitely hard for more passionate developers to realize when time to value ratio has diminished to the point that your time is better spent on other projects. There's always one more thing to spruce up or optimize. Having been both a musician and developer, I like to think of my work as a reflection of me. Playing an instrument is similar in that there is always more to learn and practice on any given song, but sometimes you need to put it down and move along to other pieces. Even the best musicians play a variety of songs. I'm sure Eddie Van Halen could have perfected Eruption for the next 20 years after he recorded it, but he decided to spend his time on other works.

Smell

"only a smell in my opinion if they are hard to read"

A friend of mine used to say: "Source code is like shit, it stinks when it's not yours."

Re:Maturity = Mess

And on a related note - why rewrite? Can't people ever just go for cleaning something up? No cause then you are just doing mindless reformatting - while if you rewrite, you can claim you make it better, faster, whatever... So of course people will say its better to rewrite...

On one project I'm currently working on, we DO just clean up the code. It's necessary because over time developers (myself included) haven't been following the coding standard for the project. To make the code more readable to future developers, we actually will try to clean up a file or pieces of a file when we touch it (comments, style, magic numbers, etc.). There are a lot files, and it hasn't always been a success (it's a continual battle), but it's better than rewriting it.

Now, I *have* rewritten a lot of the code on the project, but not because it was "ugly". We had quite a lot of "prototype" code still in the project. Since it was prototype code, it didn't check for or handle error conditions very well (not to mention the endless bugs that have been found due to the prototype code). We've had to rewrite a lot of the code because it was easier to do that than fix the bugs in the code. This usually allows for easier debugging in the future AND gets rid of any of the bugs that were found (the bugs were usually caused by a bad or even completely wrong approach to the implementation).

The difference is knowing when to clean up the code and when to rewrite it. If a developer just can't understand the code (because it needs cleanup or it's just very complicated), then it should be cleaned up and commented properly. Sure it's tedious, but everyone on the project loves you afterwards because they can suddenly understand the code! If there are bugs and it's obvious the implementation should have been done a different way (for speed, usability, modularity, whatever), then a rewrite might be in order.

(and of course, as you mention, as time goes on the code starts looking "bad" or "old" again - time for hopefully another cleanup rather than a rewrite)

what?

"Practically any time I hear a large software system discussed I hear "X is a #%@!in mess,"

I get that with reading the next line you get the context, but was I the only one taken aback at this seemingly blatant flame of our beloved X?

BOOST

The boost libraries tend to be a pleasure to work with. BOOST::Python especially continues to surprise me by how much it 'just works'. That said, I haven't had much need to look at the source code itself, but there seems to be a strong desire in the boost community to do things in as clean a way as possible.

Are you kidding?

Boost is what I call "template madness". It uses template metaprogramming to the max, which (in the real world) means three things:

      (1) It's impossible to debug. You can't read the code. The debugger can't unravel the templated variables and stuff in any meaningful way for you. You can't even step through code, that's doing a supposedly simple operation like memory allocation!
      (2) Some compilers will choke on the code, or compile it wrong in subtle ways due to differing interpretations of some obscure section of the enormous C++ language spec.
      (3) The error messages from the compiler are useless. You have to run them through a filter to even figure out what they mean.
      (3) Bugs in the library are very difficult to fix. Template metaprograms are essentially programs written in a functional language, except one that has horrible syntax. This is not the stuff that normal C++ programs are made of.

Your mileage may vary. My day job is working on a game engine for an upcoming Xbox360 game. Engines are hard enough without impractical crap like template metaprogramming in them. Give me straight-line C/C++ code any day.

Re:Are you kidding?

Mod up. AC knows what he's talking about.

Even beyond that, Boost fills up the symbol table quick as hell, because of how templated it is. I worked on a project that used LuaBind, which requires Boost, extesnively. We eventually had to swap over from Visual Studio 2003 to 2005, because of Boost's templating filling up the symbol table. Visual Studio would just fail to compile. Lua's hard enough to debug as it is, but tossing Boost on top of it made it impossible.

BOOST::Python, but you haven't seen the source???

At least you admit to being uninformed.

I haven't looked either, but I happen to know that BOOT::Python often does NOT work. It has thread-related problems.

At for the rest of BOOST, I've looked at a good chunk. BOOST makes decent programmers cry. The other follow-up post by the Anonymous Coward Xbox developer has it all correct.

I'll add:

BOOST is full of butt-ugly hacks. Check out the, uh, template things, named _0 through _9 being used as stand-in dummy arguments. Eeeeeew!!!

BOOST looks easy to dumb-ass programmers, but these programmers leave bugs that are difficult for expert programmers to find.

BOOST makes compilers run very very slow, and often breaks the optimizer anyway.

Understanding != Writing Code

It is my experience that reading and understanding code is dramatically more difficult than writing code. It gets even more difficult if it isn't your own code. Commenting, design, layuot, good structure, documentation all reduce this fact but never remove it. I've seen plently of good programmers declare code "ugly" because it had a few warts but in reality they just couldn't understand it.

Inconsistency

I find the thing that really makes code unreadible is inconsistency. This is particularly true of languages like C++ where there is no well defined one true coding convention. If all your code is in house, this is not such a problem, because you can define your own coding convention and stick to it. If however you are relying on other libraries, chances are your going to end up with one library that names its function like_this, and one likeThis, and another fnct_LikeThis ...

Worse is when you don't even define a coding convention for the code you throw into the mix. Now you have libraries with inconsistent naming, and multiple developers all using their own favorite notation.

Additionally, their is inconsistency in the functioning of libraries. Some use function pointers, some work by inheritance, some (like glade) read the export list..

I'm not a huge Java fan, but I think they have maintainability down pat. Very consistent language, well defined coding convention, and a mature set of defacto tools (JUnit, javadoc, log4j, struts, spring, hibernate, etc..) make it a lot easier to jump into older code because everything feels familiar. In most other languages you have to spend quite a bit of time just decrypting the existing code, and then more time learning the particular API's they've chosen.

anything in BASIC

The more GOTOs the better!

good source

The source for Tcl [sourceforge.net] is widely considered by those who have worked with it to be unusually clean and clear.

TeX

Can't say from personal experience, but I hear that the TeX source is a truly enlightning experience. Knuth is all for literate programming, you see.

The linux kernel

It's code is pretty good. The quality and formatting standards are pretty high for the kernel, which shows in the research about bugs/line ratios too.

Disgust

Practically any time I hear a large software system discussed I hear "X is a #%@!in mess," or "Y is unmanageable and really should be rewritten." Some of this I know is just fresh programmers seeing their first big hunk o' code and having the natural reaction.

If only mess you see when reading code, then programmer you are not-- a programmer must have the most serious mind, the deepest commitment. See more than mess, he must.

python

Just about all code I have seen written in python is great looking stuff..mainly because of
the imposed indentation and clear language characteristics.

Amazing

"X is a #%@!in mess," or "Y is unmanageable and really should be rewritten."

I see those all the time as comments in my own code.

postfix

postfix (the mail program) looks pretty nice to me.

There are different types of messes

My first large project I ever attempted (HERMES, now abandoned, http://hermesweb.sourceforge.net/ [sourceforge.net] had, I believe, reasonably pretty code. Architecturally, there were some pretty parts too. But overall, the architecture was a mess simply because I didn't know better. I eventually abandoned it because I realized it was going to be impossible to fix the initial design mistakes without entirely replacing a large percentage of the code.

My current large project is LedgerSMB. This deals with an entirely different magnitude of mess. Essentially we forked from a codebase which we have come to understand is nearly unmaintailable and yet we *have* to replace all the code because we have lots of users on the software who rely on it. Hence we are refactoring with an axe.

The older codebase (SQL-Ledger/LedgerSMB 1.0/LedgerSMB 1.2) has a number of architectural limitations and issues, as well as a lot of evidence of an overall lack of architecture. If that weren't enough, the code is pretty problematic too. It could be worse (at least the codebase is reasonably readible if you put enough effort into it).

I think it hits about 75% of the software programming antipatterns mentioned on Wikipedia, and extends some of them in weird ways. For example instead of just magic strings, we have magic comments (comments which are actually part of the program code and which deletion causes problems). And we have function calls which pass by "reference-to-deferenced-reference." In perl terms \%$ref.

Hence we are moving everything to a new and *cleaner* architecture.

OpenSolaris

As large and old as it is, OpenSolaris [opensolaris.org] has fairly readable code. Plus, most of it has comments explaining why it's done the way it is.

Re:im hesitant..

My take on C++ is that the best programs only use a fraction of the features. The language is so big it is dangerous. Just because a feature exists in the language, does not mean it is good for every application. I am very wary of operator overloading and templates too. You need to make your code sufficiently clear that you can be sure it works. if you cannot quickly understand your code, then chances are you made a mistake.

Any app that doesn't need to be rewritten...

"Any app that doesn't need to be rewritten hasn't grown sufficiently beyond its original intent." - Jesse Litton, 1990

A experiment

I wrote a Perl filter that took C code as input, and applied all kinds of "unprettifications" to it (removing comments, collapsing variable declarations, introducing random curly-brace and indentation styles, removing whitespace or adding strange whitespace). The output looked like it had been written at 3am by a hung-over ex-FORTRAN engineer who had just discovered FORTH.

Then I demonstrated that a bunch of code checked into our system looked like it had *already* been run through this tool. After the public shaming, a couple of the offenders cleaned up their acts for a while, but they're back to their old tricks.

These days I'm working on a project where all the devs are really, really serious about the formatting and naming conventions. Some of the rules suck, in my opinion, but there's a lot to be said for consistency.

[In the 80s, HyperCard team at Apple used to regularly run their sources through a Pascal formatter. The code, in a friend's words, "looked ironed." Unfortunately I haven't run across any good C++ formatters.]

Pretty code can be found here

Phoenix Technologies used to make both BIOS and printer software. The printer software department split off and became a different company, and then I lost track of them...

They made printer software that went into virtually every printer not made by HP at the time. Canon, Ricoh, Lexmark, or whoever would come out with new hardware and license the software from Phoenix. Yep, some of my code is in every Lexmark printer right now.

They had a couple hundred thousand lines of code that did PCL, GL, and Postscript for the consumer market, and it was the most readable and well developed code I have seen. Comments were explanatory, variables were well named, and execution paths were well defined and easy to follow.

They really had their act together for testing as well, with an elaborate and comprehensive regression suite that checked *every* aspect of all of the [printer] languages, and a team of QA people who would go over the results nightly. I'm not making this up - you would come in to work in the morning and there would be maybe 5 E-mails from QA outlining bugs which were either in your code or assigned to you for reasonable reasons.

We did the software for the first Lexmark printer. The first internal release gathered 900 bug reports from QA. When we went to market there were 7 remaining, all of which were deemed inconsequential.

When you are in the commercial market making fixed-program computers (dishwashers, printers, cell phones, VCRs) you don't have security updates and new versions, and a recall is usually out of the question. It's much cheaper to do all of your QA up front and ship a quality product.

In my opinion we've grown sloppy in the programming business. I've been a contractor for the past 30 years and I haven't seen anyone else who comes close to true quality procedures. Even FAA safety certified stuff is usually hokey and obscure. Thank god we've still got human pilots.

Having seen the procedures firsthand I have an appreciation of how easy and valuable it all is. No one else seems to understand that, and so everyone keeps running around putting out fires and slipping deadlines.

Bourne Shell

The Bourne Shell [tuhs.org] must get some kind of mention here. What do you do if you prefer ALGOL to C? Why, #define your own syntax [tuhs.org], and thus turn boring old C code into a thing of beauty [tuhs.org].

Why Old Code isn't pretty

Many pieces of old code aren't pretty for a fairly defined set of reasons:

1. a) Debugging Ensure you actually have an appropriate way of debugging the code. The systems I work with are embedded and run 7x24. People will say: it failed last week on Wednesday at 3:00 A.M., we got it working, but can you fix the problem? The problem may not actually be your code, it could be another piece of equipment. In any case, you need to figure this out from the logs. In my experience, many "pretty" programs are too small to justify extensive logging. After logging is included, the programs become less "pretty" but much more maintainable.

1. b) Refactoring after Debug Sometimes the results of the debug will show a major design error in the program. You now need to implement a major architectural change that really was not originally intended. You have good modular code when it can withstand these major design changes in a relatively smooth manner.

2. Failure to handle common areas of problems well These include:

2. a) Strings Does your program have the ability to smoothly handle unicode/UTF/HTML/locale specific strings? Every different language you port your application too, and every different program you talk with, will all have differing definitions of what is a string. My favorite test case is CNC (Computer Numerically Controlled) machinery. Some CNC machines expect embedded nulls inside the strings. The embedded null requirement affects a surprisingly large number of string libraries.

2. b) MessageBox() Invariably in a big program it will be unacceptable to allow it to hang on a modal dialog box like MessageBox(). How are you going to handle it? What if a library call executes a modal dialog box?

2. c) Handling Exceptions For a simple prototype program, handling exceptions is not a big deal. In a production application, all the exceptions must be handled appropriately and the program must be able to continue when exceptions occur. The error handling code often exceeds the size of the original program.

2. d) Third Party Libraries / Operating Systems (Windows) The amount of code devoted to covering up mistakes in other code is amazing. Unfortunately, unless coding on an open platform, one must accept the costs of the additional code. When starting a new project, I recommend thoroughly stress testing any new libraries that will be used. Thus one can find the killer bugs that significantly affect design decisions.

I would appreciate any feedback/additions to the items on this list.

Donald Knuth once apparently said

that he thought Bill Atkinson's MacPaint was the most beautiful program ever written. Hearing this, Andy Hertzfeld made it a priority to recover the source code from an old Macintosh diskette. He contacted me because he was a bit worried about Apple's reaction if he just released it on the net (since it was Apple property), and I advised him to get the Computer History Museum involved if he didn't want to take the risk. I believe that he donated the code, but I'm not sure what the Museum did to have it made available.

The MacPaint code was donated...

Andy mentions this topic towards the end of an interview with Bob Cringely on Nerd TV. At the bottom of this archive of NerdTV episodes [pbs.org] is a link to episode number 1 in a variety of formats. Here's the transcript of the Nerd TV interview [pbs.org] where Andy says

So I was thinking of putting it on the site, Apple would send me a cease-and-desist, I'd take it down, but it would be out there then. But I was just a little too chicken. Finally Tim O'Reilly came up with the brilliant solution of donating it to the Computer History Museum as a historic artifact. Perhaps they could get permission from Apple. So that's what we did. It took a few months but [i]n August Apple approved the donation of the MacPaint source code to the Computer History Museum. This was their first major software artifact in their collection so they made a big deal of it, made a video of us, and eventually the MacPaint source code will be available from their web site to anyone in the world.

It's just occurred to me you are Tim O'Reilly. Wow, there are still some important folks that still post on /. ! Your company gave me some free books and a T-shirt when I was in my second year of University, thanks! Many of the well known people who used to post here have abandoned it in recent years so the feel of the place has changed. The only big name I still see around here is Jeremy Alison from Samba...

...and Knuth should know

As the inventor of "literate programming"[1], early practitioner of open source, and author not just of The Art of Computer Programming and its included programs, but some extraordinarily elegant and widely used software systems himself (including TeX and METAFONT). How many people's programs are worth printing as hardcover books?

[1] mention also to Kernighan & Plauger's Software Tools.

We just published a book called Beautiful Code.

So this post is perfectly timed. It's a collection of essays by leading software engineers about code they find especially beautiful.

Andy Oram, the editor, thought it would be poor form to make a post himself, but heck, I thought: this is very relevant. The table of contents for the book can be found at http://www.oreilly.com/catalog/9780596510046/toc.h tml [oreilly.com]

It includes essays by Brian Kernighan, Jon Bentley, Tim Bray, Yukohiro Matsumoto, Simon Peyton-Jones, and many others. The code is intended not only to be beautiful but also instructive and in many cases re-usable.

We're hoping to build an ongoing site around the book so additional examples would be very welcome.

A chapter in "Beautiful Code" is on this topic...

Laura Wingerd and Christopher Seiwald wrote an excellent chapter on this topic for O'Reilly's Beautiful Code [oreilly.com] book (just out). See Chapter 32, "Code in Motion". The code from their chapter is online here: http://www.perforce.com/beautifulcode/ [perforce.com]

pretty driver code...

I've always been impressed by the BusLogic SCSI driver code in the Linux kernel. Anyone interested in what a good low-level, bit banging C program should look like should study its code carefully. Here is a randomly chosen snippet: /*
        The Modify I/O Address command does not cause a Command Complete Interrupt.
    */
    if (OperationCode == BusLogic_ModifyIOAddress)
        {
            StatusRegister.All = BusLogic_ReadStatusRegister(HostAdapter);
            if (StatusRegister.Bits.CommandInvalid)
                {
                    BusLogic_CommandFailureReason = "Modify I/O Address Invalid";
                    Result = -1;
                    goto Done;
                }
            if (BusLogic_GlobalOptions.TraceConfiguration)
                BusLogic_Notice("BusLogic_Command(%02X) Status = %02X: "
                                                "(Modify I/O Address)\n", HostAdapter,
                                                OperationCode, StatusRegister.All);
            Result = 0;
            goto Done;
        } /*
        Select an appropriate timeout value for awaiting command completion.
    */
    switch (OperationCode)
        {
        case BusLogic_InquireInstalledDevicesID0to7:
        case BusLogic_InquireInstalledDevicesID8to15:
        case BusLogic_InquireTargetDevices: /* Approximately 60 seconds. */
            TimeoutCounter = 60*10000;
            break;
        default: /* Approximately 1 second. */
            TimeoutCounter = 10000;
            break;
        }

This is some seriously low-level stuff, and it reads like English text. It totally changed my ideas about what this kind of code should look like! It believe it was written by the late Leonard Zubkoff.

Young Programmers...

...almost always want to re-write old code from scratch.

Almost always without taking the time to understand what that old code does. Why? Because writing code is much easier than reading code. Reading code takes perseverance and ability to focus on large numbers of nit-picky details. Something our TV-age brains cannot easily do.

The result of throwing out the old code without understanding what it is accomplishing is not always positive from a business perspective.

Sure, sometimes crufty code is crap.

But sometimes, like on a terminal emulator project I worked on in the mid-90's, the cruft was a bunch of code, accumulated from 1985 to 1995, that actually emulated the bugs in the firmware of 10 different manufacturer's dumb terminals. The programmers who wrote the applications that ran on these dumb terminals relied upon these bugs in the firmware and when the bugs disappeared, the applications broke.

The company that tried to sell the "correct", "new", "elegant" terminal emulator hit a big solid brick wall called "market acceptance." The company that kept the cruft made roughly $4 million per year in profits and supported 25 employees' and their families for a decade while they developed new products.

So, before you look at code in a shipping product and say to yourself "this is crufty crap and should be re-written from scratch" ask yourself this question: "Do I really understand what this crufty crap is doing?"

Buy a book (Norvig, PAIP)

Peter Norvig, now CTO of Google, agrees with you. Coding, like writing, is best improved by an alternating diet of writing and reading good works. He collected a few of the best he'd found in a book called Paradigms of Artificial Intelligence Programming, available from his web site or from Amazon: http://norvig.com/paip.html [norvig.com]

It talks about AI because it was the 80s (92 by the time it hit shelves) and AI was cool---but the applications involved are now just what we call computing. It's not perfect: fifteen years have passed since it was written. In that time, C++'s STL and Boost have caught up with many features of Common Lisp. Java's come along and done well. Other interactive dynamic languages than Lisp exist: Python, for example. So you'll have to do some translating in your head---but for the same reason that Cicero is read by students of English rhetoric, Norvig should be read by C++ and Java programmers seeking mastery.

The Tandy CoCo

Limitation is the Mother of Pretty Software.

I remember when that cute little home computer came out, and all the programs were just so. . , plinky.

Memory was a huge barrier, because you only had a small quantity of the stuff, and nobody understood the architecture of the system well enough to produce efficient programs.

But back then, there were no video card upgrades. No faster processors and mother boards being produces every three months. If you wanted higher speed and cooler graphics, you had to write your code in more ingenious ways.

And so that's what happened.

By the twilight years of the Color Computer, the games people were writing on that thing were unreal. I remember looking at a few and thinking to myself, "This is the same computer? Wow! Humans rock!"

When you reach the raw power limitations of your muscles but you still want to improve yourself in your combat skills, you take up Kung Fu. That's how it was in the old home computer days. Nowadays, though, (dang kids; I hadda walk fifty miles to school!) it seems that the bulk of improvement comes with the purchasing of increasingly large muscles.

This is not to say that there is no software innovation. Heck, id Software did some pretty amazing things with software ingenuity. But I do remember thinking during the first few years of the big PC revolution, after the 486 was reaching its twilight, "You know, all this hardware innovation is great and all. . , (big muscles are cool), but part of me wishes it would stop cold for six solid years just what would happen when the programmers were really pushed. --You know, to see what one of these machines is actually capable of doing.

-FL

Golden Code

What you're asking for is often called Golden Code or Golden Pages and usually exists within large software engineering companies. The problem with gaining access to such things is that they usually are considered very important to the organization who owns them, so they are not made public - they're more or less considered trade secrets, a guide to that particular company's proprietarily developed best practices.

The other problem with easy access to Golden Code is that it must be constantly maintained to remain... "golden." So even if someone were to post a great example online, they're probably not getting paid to do so, so it's probably going to lose its luster in a couple years. Companies who maintain Golden Code usually assign a particular product to be coded in a "golden" way and continuously maintained in that perfect state as an example to all. This requires a lot of money.

So the point is, if you want access to Golden Code, get hired at a big software company. There are a fair number of them out there if you look outside the most obvious markets. Enjoy.

OpenVPN, glib

OpenVPN is very well-written C -- clean and accessible. Likewise for glib (not glibc, glib), presuming one likes the fun it does with macros.

Gled

Take Gled (http://www.gled.org/ - a recent CVS snapshot is preferable), a distributed C++ application builder with OpenGL/OpenAL/FLTK interfaces, object persistence and excellent extensibility.

It certainly is not pretty the first time you look at it, that is probably true for any unique project, but if you look harder, you will see a strange tangle using ROOT, CINT the C++ interpreter, built-in C++ object dictionaries, elegant and fast network stack for object streaming and synchronization, and strangely effective remote procedure call interface. But my favourite is the auto-building FLTK gui.

While remotely involved, I do enjoy this code immensely.
Try building a new library for it and enjoy GUI-enabled objects in minutes... (There is even a scratch for a TA-like game in one of the demos, not yet playable.)