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.