picture home | pixelblog | qt_tools

omino code blog

We need code. Lots of code.

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.

Douglas Jones // Thu 2006.09.7 07:457:45 am

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.”

David Van Brink // Thu 2006.09.7 14:522:52 pm

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.

Nearly every software professional has heard the term spaghetti code as a pejorative description for complicated, difficult to understand, and impossible to maintain, software. However, many people may not know the other two elements of the complete Pasta Theory of Software.
Lasagna code is used to describe software that has a simple, understandable, and layered structure. Lasagna code, although structured, is unfortunately monolithic and not easy to modify. An attempt to change one layer conceptually simple, is often very difficult in actual practice.
The ideal software structure is one having components that are small and loosely coupled; this ideal structure is called ravioli code. In ravioli code, each of the components, or objects, is a package containing some meat or other nourishment for the system; any component can be modified or replaced without significantly affecting other components.
We need to go beyond the condemnation of spaghetti code to the active encouragement of ravioli code.
— Raymond J. Rubey

The problem is that we each of us can read these sentiments and think, Oh yes, of course I do that!

oh, i dont know. what do you think?

(c) 2003-2011 omino.com / contact poly@omino.com