Revision

In the two years I’ve been at the university, I’ve taken a few classes on literature. These have been very enjoyable; essentially, literature class teaches you how to analyze things, how to look at their details and understand them in a more in-depth manner than you normally would.

The fact that literature is the subject of this analysis is more or less incidental. It’s handy because books (at least those that are well-written) generally carry many layers of meaning and tend to be fun to read. Really, though, we could be analyzing films, advertisements, even comics¹, and it wouldn’t matter; the basic principles would be the same.

You could even analyze code. I think that would be quite an interesting exercise; take a chunk of code and subject it to literary analysis. There’s actually a strong mapping between code and prose. If the code won’t compile, that’s a grammar mistake. A logic error maps on to a mistake in an argument or a plot hole.

But literary analysis isn’t interested in grammar or plot holes. It’s interested in looking at the text on a different level. For example, for a class last winter, I wrote a paper on F. Scott Fitzgerald’s use of semicolons in the The Great Gatsby. Semicolons! What’s more, it was a very good essay; I got full points.

That may sound trivial or bullshitty, but it wasn’t. Whether consciously or not, whenever Fitzgerald used a semicolon (and he used them sparingly, which made it interesting) it had a very particular effect in the surrounding narrative. Looking for that and thinking about it gave me a much better understanding and appreciation of the text, and of the power of language than I would have had otherwise.

Could a literary analysis of code have the same effect? Of course, you wouldn’t look at semicolons; they have a different purpose in code than they do in text. But things like idioms, patterns of coding, naming conventions, abstractions… I think carefully examining those could be very useful for understanding the code itself in a different way than “it does so and so.”

Contrary to what my prior rambling would suggest, though, I don’t actually want to focus on the similarities of reading prose and code for this post. I want to talk about the similarities of writing them. Specifically the process of revision.

I’m reasonably good at writing papers. I can pretty consistently produce not-too-bad papers, even when I’ve procrastinated far too long, when I’m low on sleep, and occasionally, I admit, when I’m not that familiar with the subject matter. These papers end up receiving decent grades; sometimes I’m even proud of one or another of them. But they aren’t really good papers.

I can sometimes write really good papers. A lot of what goes into this is just removing all the mitigating factors and writing it with plenty of time, when I’m reasonably awake, and after I have a good understanding of the subject. But these aren’t what tips the balance. Rather, they all enable the one thing that really makes a good paper: revision.

Code is much the same way. It’s pretty easy to write something that works. You can always brute-force a problem, or let the user figure out the interface, or leave in that bug; really, how often will it pop up? It’s easy to just call it a beta, release it, and be done with it.

Of course, we all know that it would be terrible to leave it at that. The parallel in writing prose would be to write out a list of the points you’re trying to make, and leave it at that. No examples, no explanations, nothing to aid the reader in the slightest. Add some bullet points and it’d be an outline.

This is the first stage of revision. It’s not hard; you already know where all the problems are. Your work is cut out for you: make the algorithm O(n log n) instead of O(n²). Add a help message, meaningful options, maybe a GUI. Get down on your metaphorical hands and knees and debug.

This is when you get to the tricky part. Once you’ve finished the first revision, you get something passable. Passability is the nemesis of anyone working towards excellence. If you called the software done, no one would think twice about it, at least at first. If you turned in the essay, you’d get a good solid B².

But that’s not good enough! Well, actually, I guess it’s sort of good enough by definition. But it’s not very good. And the most important part of making that step is, once again, revision.

It’s still reasonably straightforward. For an essay, all you really need to do is print it out³, read it over, and make changes wherever you see something that doesn’t read right. For code, you just need to write a bunch of tests and change anything clunky, repetitive, or just ugly that you see⁴. That doesn’t seem too hard.

Really, it’s not too hard. The trick is to get yourself to do it. Goodness knows I’ve failed at that enough times, for both media. It takes time and energy. Your code/paper is already passable. Is it really worth it? I think that in the vast majority of cases, it is. For code in particular, the only reason it might not be is if your code isn’t going to be reused. If that’s the case, your solution isn’t general enough and you should fix that. And any medium, making your creations as great as they can be is valuable in itself.

This isn’t a surefire recipe for greatness, of course. That takes many more revisions, each of which gets harder and requires more ingenuity as all the obvious improvements get made and the only ones left are those that are sticky and hard-to-find. Even then, there’s nothing sure; I’ve seen (and written) papers that have gone through revision after revision and still ended up mediocre. But every time they were revised, they ended up better than they were before.

¹ I’ve actually analyzed all three of those for a literature course once. That was lots of fun.

² I’m using a letter grading here for lack of any sort of standard essay-grading scale. I don’t think I’ve actually received a letter grade for two or three years.

³ Printing out a paper you’ve written on the computer is a surprisingly helpful revision aide. I don’t know whether it’s the ability to make physical marks on it, reading it as the audience (presumably) will, or just seeing it in a different context from how you wrote it, but it gives you a great new perspective.

⁴ I still don’t buy the test-first philosophy, in large part for this very reason. If you test first, you don’t have the same encouragement to look critically at every bit of your code. Maybe testing first makes the code good enough that this isn’t necessary, but I doubt it.