I have a lot of stuff in my Applications folder. Even on my MacBook Pro’s 1920×1200 display, the dock would be severely cluttered if I actually had all of the stuff that I use fairly frequently on it. Instead of having a cluttered dock, I started launching things through Spotlight. This was a step in the right direction, because it saved me from going to the finder for Applications I used more rarely, and it’s easier than looking through a stack for the Applications folder. The only problem is that the spotlight search feels slow, since I’m comparing it to the the run menu in GNOME or Enlightenment. Quicksilver is fast. I find myself removing things from the dock unless I run them every time I log in, because running them through quicksilver is inevitably faster.

I am also enjoying Quicksilver’s ability to figure out what text is. Bringing up quicksilver, typing a url or an email address, and having a Safari or Mail.app window open is great. Putting ideas into DEVONthink—which I am just starting to use—is also pretty straightforward once you toggle the “switch to text mode if no match is found” option.

There’s a lot of power behind Quicksilver. Try it, and soon you’ll miss it wherever you don’t have it.

I’d like to start with an english language example of self-documenting code. It’s for building Lego.

Take an 8×2 red brick. Now take four red bricks which are 2×2 on the bottom and 1×2 at the top (slant pieces, as I called them when I was a kid). Put them on top of the 8×2 in two pairs with the thick parts together. Take two red upside-down slant pieces (2×2 on top and 1×2 on the bottom) and put them on the bottom of the 8×2 at the far ends with the thick parts facing inside. Put a 6×2 red brick between them. Take another two red upside-down slant pieces and put them so the thick parts are on the outermost bumps of the 6×2 with the slope facing outwards, and put a 4×2 red brick between them. Repeat this, but with a 2×2 brick in the middle. Finally, put two red upside-down slant pieces on the bottom, with the thick parts together.

If you followed these instructions properly, and if I wrote them properly, you’ve now made a red heart, because I love you.

So here’s the thing about self-documenting styles: they document what’s being done to solve a problem, but not the problem that’s being solved. If the self-documenting code above had appeared after a comment that said “this makes a red heart,” everyone could have saved their time.

Here’s the fundamental point: code is a solution to a problem. To use code, you need to know exactly what problem the code solves, so you can find a way to express your problem in the same terms. If you have a digestive system (a solution to a problem) and a sandwich (data) and you’re hungry (a problem), you can solve the problem¹ by breaking the sandwich into pieces that are suitable for your digestive system (this is one problem that the mouth is a solution for). But self-documenting code does not explicitly document the problem that it solves; it only documents how it solves it. If it’s clear enough, you can figure out the problem from the solution, but it takes a while, sometimes longer than solving the problem took—as is probably the case in the lego example above. If you’re given a disembodied digestive system and all you know about it is that it’s a bunch of funny tubes, you’re not going to be able to do much with it. You might make sausage.

Even in cases where most of the problem can be immediately figured out, say a function called DisplayImage(), there’s still the issue of figuring out how the problem should be expressed. Say you’re passing it the pixel data and the length and width: is the pixel data an array of rows of pixels, or is it just a lump of pixels that gets divided up given the length and width? Is it one image where every value is RGBA, or is it four images, one for each channel? With a self-documenting implementation, you still need to read the code and figure it out from how the data is used. A Doxygen header here could answer would answer all of these questions concisely.

Now, self-documenting style is still vitally important, as anyone who has gone bug-hunting in a pile of spaghetti code² with one letter variable names will tell you. It makes bug-hunting infinitely less painful. Everyone should always use it, but if your code is meant to be used as a library or elsewhere in the application, it should never, ever, ever constitute “documentation.” It should become a black box with labels on it. “Chips and pop go in, web sites come out.” This part can only be done with documentation that is separate from the code.

1. You can also solve the related poo-generation problem.
2. The disembodied intestines are spaghetti code in several ways: they’re tangled, uncomfortable to debug and they solve the problem of what to do with spaghetti.

There are a lot of predictions that one can make based on the size of a company. Smaller companies have a higher expected rate of return, since their smaller size increases the risk associated with any project. Along with that higher expected rate of return is a sharper decline in the future value of money compared to the current value of money, and by extension a sharper decline in the value of future effort compared to effort now. This kind of thinking makes smaller companies more inclined to not clear 40 man-hours to document a code base, knowing that in a year, when they expect to need to bring on another 10 programmers to handle the growing development load, it will cost well over 40 man-hours to bring them up to speed. Additionally, that documentation would save time when designing new features by clarifying the ways the new features must interact with existing ones. The same goes with unit testing, which has an up-front cost but saves a lot of time once things are being added: not only does it provide yet more documentation of the expected behaviour, it provides free regression testing once the change requests start flowing in. These are investments that keep on returning: they will save developer time for the entire length of the project.

Now, there’s a terrible thing that can happen in a software project, which I’ll call the “Oh, Shit” Moment (OSM). This is the moment where one realises that one’s code base is incapable of supporting a change request or important new feature without considerable rework, or the moment the senior-most members of one’s team start spewing profanity and quit. These moments happen often in the real world, especially with small companies where the scope of the software isn’t well defined. For a small software company, an OSM can mean something as small as a few dozen unplanned programmer hours (ie, a few thousand dollars), or it could mean abandoning a significant amount of new code due to unexpectedly high integration cost, or it could mean a huge rewrite and possibly the end of the company. So how do testing and documentation affect OSMs?

• No matter how readable one’s code is, design documentation is always more readable. This helps new developers come up to speed quickly and saves existing developers time when they use code that has lain untouched for months or years. This can both prevent and diminish the impact of an OSM.
• When a bad design decision has been made, it tends to become much more obvious when one tries to explain it in plain language (and for some reason needs a thousand words); this can prevent some OSMs from ever happening.
• A module which needs to be rewritten can avoid re-integration problems much more easily if there is a unit testing framework, or at least a well-documented interface that it must adhere to. This will considerably reduce the impact of the OSM.
• Unit tests created as bug-fixes from the original version are documented summaries of things to be careful of the next time around.
• Documentation provides a clearer overall picture of the project, which will significantly aid decisions which must be made about the design and implementation of a module which must be rewritten. This and the last point can turn an OSM today into a blessing in the future.
• Documentation will help when it comes to estimating the development and integration cost of new features, which will help prioritize new features as well as see OSMs on the horizon.

Smaller companies may not have more to gain from keeping good development practises than large companies, but they have a lot more to lose. If a project at IBM fails, IBM shrugs, writes it off and continues being an enormous and generally profitable company. If a project at a small company fails, it means a significant financial loss, if not the loss of their entire ability to generate new revenue. We want to keep that rate of return high, and it’s worth that little extra investment up front. Really.

By way of an explanation, consider a zen koan.  It’s relationship to zen is very, very much like the relationship of design patterns to good programming.  A koan is not zen.  It does not describe a zen state, but, if one looks at it properly, one can (un?)learn something about zen.  Memorizing a million koans will not bring one any closer to zen than memorizing one.  Doing as the characters in zen koans do does not bring one any closer to achieving zen.  Making a practice of kicking things over when you’re asked to describe them is probably not as appropriate as it was for Joshu’s cook.  There is something to be figured out in the koan, and once one understands it, the koan should be thrown away.  It is a linguistic container for the idea; the idea itself is necessarily more elegant and more compact.

Similarly, knowing lots of design patterns isn’t going to really make one a better programmer.  Using design patterns will probably result in better code, but it won’t, by itself, make one a better programmer.  Unlike zen, good programming can be described quickly and succinctly: getting the most good code with the least effort.

For example, the concept of MVC can be applied to a web service.  There’s a model for the data, a controller to do stuff with it, and a view that decodes method calls and encodes responses.  Let’s say that it’s an XML-RPC service: all the view does is convert back and forth between XML and locally usable data structures (assuming the controller validates its input properly).  Significantly, these structures are passed directly to controller, and what the controller returns is probably encoded and sent right out.  There is nothing significant happening here.  The view is extraneous.  In turbogears, for example, one could use the CherryPy to do the conversion; I believe the whole process is no longer than four lines.  Even in something as primitive as C or PHP, the view for the whole application, regardless of size, can be implemented in one function.  There’s no point in setting up a sacred View pedestal to put it on.

The lesson to take away from MVC is that by breaking a certain class of application into these three components, it becomes easier to modify any of the components without needing to change the others.  It prevents rewriting and saves effort, and less effort is better programming.  Once this lesson is learned, MVC as a strict thing can be thrown away, and the idea of compartmentalization that it provides can be applied in some form where appropriate.

The same applies to other patterns: they are ways of approaching specific classes of problems.  Although some of them are damn clever (think: visitor pattern), one will almost never run into a problem where the pattern, taken verbatim, is the best way to solve it.  What they are is programmer-koans that provide insight into the nature of the problem at hand, and the nature of good programming.  Design patterns are not good programming.