As I mentioned previously, a lot of the projects I’ve been working on over the past year have been largely uncommented. This wasn’t viewed as an issue by the people working on these projects because the company had a heavy focus on using a “self-documenting” coding style. I’d like to take a moment to explain in somewhat greater detail why this is, frankly, very stupid, especially on any non-trivial project that doesn’t have a permanent team.

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.

This entry was posted on Monday, February 4th, 2008 at 6:11 pm and is filed under Geekery, Smart-Sounding Babble, Software. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.