Read part one first, please!
Bad Code
The experience of Bad Code comes from the following dissonance:
- You want to use this code, either as a library or perhaps to improve or fix it. (In some settings it may be that you have to use it.)
- It resists being used.
In extreme cases, a body of source code doesn’t build. But even if it does, if you can’t discover a way to use it then it has become Bad Code.
I believe there’s two things which contribute the most vigorously to the badness of Bad Code. I’ll enumerate these, and then offer a speculation on how this comes about.
Badness 1: No Examples
Examples can come in many forms. For something downloaded from the interwebs it might be a folder named “Examples”. Nothing wrong with that.
But if it’s a library from the guy in the next cube, it might just be an email with some stuff pasted in, or even some whiteboard scribblings. Remember, I said Good Code lets you get something done in 20 minutes. Talking to the author isn’t “cheating”.
Also, as I’ve previously babbled, unit tests are great. This is another place where an example might be found.
But the key point here is that there are examples of use. And you can find them.
Badness 2: External Dependencies
Here is a recurring property of Bad Code: it depends on everything else being “just right.” That may mean that lots of other libraries have to be in place in some nonobvious way, or that files have to be in certain spots, or that environment or property variables have to be just so. And the perp will innocently say: “But why would you ever run it without all the other stuff?”
Because, my friend, that’s what makes Good Code good.
How Does This Happen?
In my recent experience, this comes about just one way: programmers following a spec.
I know it sounds crazy… but I’ll attempt to explain it in abstract pretty pictures. Here’s a spec, derived from some whiteboard discussions and some anecdotal customer feedback:
And here is the Bad Code implementation of that spec:
It looks just like the spec! Right down to every little kink and error. Of course you can’t use it for something in 20 minutes. Your product took years to develop, and this implementation knows every nook and cranny of that work and depends upon it.
And here’s my vague and unsupportable visualization of the Good Code implementation:
The spec has been deconstructed into a rational architecture. The implementation includes the spec but is not damaged by the spec. Ah, if only pretty pictures could actually be true…
Make It Look Easy
In part one I presented the Mozilla Rhino interpreter as an example of Good Code. It was self-contained and had examples, and was relatively easy to set up and run. And one could say, “Oh but that was a particularly easy case. Of course it can run standalone!” The trick is to make it look easy.
There’s an artist/mathematician named Scott Kim who is known for creating “inversions,” text art like this:
It has 180 degree rotational symmetry. A wise person once pointed out to me that, “Each of Kim’s inversions looks like it was a particularly easy one, don’t you think?” There’s always some little thing that makes it trivial. But it’s not. The trick is to make it look easy.
If it doesn’t look easy, you haven’t worked hard enough.
That’s the art.
In part three I’ll offer a couple of tips that might, just might make your code usable by someone, for example, me, in twenty minutes.
That reminds me of a quote I heard about 10 years ago. “If you can’t explain it clearly then you don’t understand it well enough.”
I agree with that!
Though… the implicit full claim would be: “If you can’t explain it clearly then you don’t understand it well enough for me to understand it.” Some people are very comfortable with complexity and transverbal software… but I don’t want to inherit their code… if their comfort level exceeds mine.
Yet another humorous retelling of approximately the same thing: http://www.gnu.org/fun/jokes/pasta.code.html.
The problem is that we each of us can read these sentiments and think, Oh yes, of course I do that!