2007/10/27

Revisiting code

Michael Mccracken said it first:

Once you get a piece of code to the point where you believe it works - it’s passing its tests - go back over it and edit it. That is, go back and edit it for clarity, flow, and style. Just as if it were an essay.

Les Orchard at 0xDECAFBAD (love that site name) said it better:

Ugly code kills motivation and comprehension

There’s a curious tension between the “it works; ship it” mentality and those that say “this code isn’t perfect; it isn’t ready”. I don’t have a background in computer science, so the code that I ship tends to be the “it works” variety; over the months and years I’ll see ways to do things better (often through bugs cropping up that shouldn’t have happened in the first place) and the code base improves piecewise.

But one thing I have noticed is that if I write really nice documentation (of both the user interface and the code itself) I’m more inclined to go back in and start messing around with little tune-ups. LaTeX’s docstrip is ideal for this because you can freely mix up code and documentation (and even present the code asynchronously). Some of my time might be wasted by choosing the font that my code is presented in, and nicely explaining my algorithms with carefully typeset figures and tables but the up-shot is that it makes things a lot more accessible for someone to edit in the future. And that includes me.

(Oh, when I say that I don’t mean it’s a good idea to program in LaTeX; it’s rather hideous, actually. But docstrip doesn’t have to be used for LaTeX programming and one day I’ll experiment with writing other code with it.)