Zen in the Art of Rewriting

More than a few people have taken the time to write and say that my writing sucks. Folks, hold your applause! It’s true, it does. This distresses me:

Zen Master Ryokan lived in a poor little hut on a mountainside. One moonlight night he came home and found a burglar looking for something to steal. But Ryokan was a hermit who owned nothing.

“Poor fellow,” he said to the robber. “You have come a long way and have found nothing. But I don’t want you to leave me empty-handed. Please take my clothes.” And Ryokan stripped, and handed the clothes to the robber.

“Poor fellow,” said naked Ryokan, going outdoors again when the inconsiderate robber had left, “How I wish I could have given him this wonderful moon.”

I often feel like there is this wonderful moon, these great truths and beauties, and when I write down what I see, when I try to share it, all I have to give you is a tattered robe. How I wish I could give you the feeling I have when I sit in the moon’s silvery radiance. But my weblog… it’s really just a tattered robe. Why is it so bad? Why do I fall so short?

Writing and coding have a lot in common. One of the most obvious similarities is that good writing is rewriting. I don’t just mean “polishing,” I mean sitting down and reorganizing, dropping stuff that really doesn’t work, finding a better organizational structure for ideas, combining a few things that say the same thing… Rewriting is hard work, much harder than writing.

One of the reasons my writing sucks is that I don’t do enough rewriting. Like many software projects, my blog is a prisoner of the tyranny of the urgent. Once a post is basically coherent, I have to choose between rewriting it and getting Real Work™ done, or writing more Nights-and-Weekend™ code written, or even between rewriting an old piece and writing a brand new piece. Far too often, I say the same thing about a new post that we all say about our software: “It’s good enough, it works, don’t rewrite it, don’t refactor until we need to.”

It’s amazing. We agonize and debate and twist ourselves into intellectual knots over whether a new language or a particular DSL or even a hack makes each line of code easier or more difficult to read. But where’s the emphasis on writing and rewriting each line of code until it’s perfectly readable?

There’s some sort of fetish for small vocabularies in our industry. This idea that if you use simple words and simple sentences, clear writing necessarily follows without further effort. This is like assuming that the smaller your vocabulary, and the simpler your sentences, the more you write like Hemmingway.

If reading code is far more important than writing it, if we really ought to be writing code for those who come behind us to maintain it, why are we talking about the difference between .map { |x| x*2 } and .map &'*2' when we ought to be talking about the difference between taking two hours to write some code and six hours to write, rewrite, and rewrite the code again?

Is it—I am speaking from my heart here—because languages and tools are glamorous? Because they are the stuff of ideas and intellectual valour? Where rewriting is just plain hard, hard work? Work that few appreciate, because the work of rewriting is “invisible” in the finished code?

In my essay about still failing, and again in my essay about bricks, I lamented the fact that what we can observe about projects and about code is only indirectly related to what is important. Rewriting is one of those things. You can look at code and say, “The Visitor Pattern adds needless cruft.” But how do you look at code and see whether this is the best that can be done? How do you know whether the author banged it out in one go or spent days making it as simple and direct as possible?

Getting back to the story of The Robe and The Moon, there is no doubt that shipping things that just work puts software into the hands of people that need it, just as Ryokan gave his robe to the burglar. But how distressing that we still fall far short of what we could be shipping, of what we could share with the world.

Yes, I admit that my writing sucks. And worse, I admit that much of the code I’ve written in my life sucks in exactly the same way. And I’m going to do better.

I’d like to start now. But first I have to get back to work.  ¶ 9:41 AM