raganwald
(This is a snapshot of my old weblog. New posts and selected republished essays can be found at raganwald.com.)

Monday, October 29, 2007
  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?




Zen Shorts is a tremendous children’s book, featuring the enigmatic Panda Stillwater and the stories he tells to help children understand their lives. It contains three of my favourites including The Robe and The Moon and The Monks and The Lady.

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.
 

Comments on “Zen in the Art of Rewriting:
WTF? Your writing doesn't suck.
 
Thanks, but honestly it could be better.
 
great, honest article.

how does one get to Carangie hall? practice, practice practice.

That probably wasn't the first time Ryokan gave someone all his belongs. Mastery of something does not come in a moment of great need, or even timely preparation. Train daily to better yourself at all you do and gradually, over-time, that mastery will unfold itself.

But of course, work comes first :)

davidgurba.com
 
“If I had more time, I would have written a shorter letter."
Whether its from pascal or elliot the phrase is still good.

The trick is in the stopping I guess. Not stopping cause you don't have enough time but stopping when you know it is right to stop. Most of our code that we write has to be stopped because of deadlines, but making sure you can go back and rewrite it allows it to get closer to "right" and usually shorter.
 
Writing and programming are different in that the primary goal of programming is to solve some problem, and communicating with other people is the secondary goal. Put another way, it doesn't matter how clear and direct the code is if it doesn't do what your customer wants.
 
Writing and programming are different in that the primary goal of programming is to solve some problem, and communicating with other people is the secondary goal.

In the past, I've tried saying this to colleagues, explaining that if I can solve the problem faster in Language X than in Language Y, we should use X.

Or using idiom W instead of pattern Z.

But for some reason, the response was always, "that would be difficult for maintenance programmers to grasp, they are too junior to understand language X and idiom W."

It appears that programming is an activity where communicating with each other is far from secondary to communicating with the machine.

My experience is that people want communication with the machine AND with people. It is obviously true that if it doesn't work, nobody cares what it looks like. But it also isn't true that if it works, nobody cares what it looks like.

Once it works, people have very strong opinions about its form.
 
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?

You make it conventional to distribute software with its version history. And you build effective tools to browse version history.
 
Just to clarify:

I am not claiming that there is a relationship between Zen and writing (be it blogs or software).

I found that something in a particular Zen story reminded me of the gap between what I feel and what I write, and then from there I went to one particular reason for the gap. There is, of course, no relationship between the meaning of the story and rewriting.

In fact, I can't even claim that I know what the Zen story is actually about. Maybe its intent is far removed from the feeling I took from it.

Oh well!

And as for the title, I intended it as a homage to one of my favourite books. That book isn't about writing either.
 
Work that few appreciate, because the work of rewriting is “invisible” in the finished code?

I feel that one very strongly. I found the following "pattern" on my own "Night-and-weekends" project:

1. I write client code as clearly/elegantly as I would like it to be

2. I struggle with the compiler (scala) and try to degrade the syntax just enough to get a compiling solution

3. I complete the implementation to get something which really works

4. I sweat a lot to rewrite the implementation to get it more simple, more to the point. In the process I may drop some "client" features to avoid an unreadable implementation.

5. I retire and meditate on all the people (including myself) who will later say:

-the client code could be better
-the implementation is a piece of cake, I would have written that in 2 hours
-the implementation is ugly

Now, the questions I ask myself are:

-is that possible to get to the final code more quickly?
-does it take just much more years of practice?
-are there some other techniques/idioms/languages which would get me there faster?

How those questions would apply to your writings? I suspect that there is a positive answer to the third question for both programming and writing.
 
The difference is between writing a novel and writing poetry.

When you're coding, you have to write a novel. The plot must not have any holes in it. All characters must be consistent and fully researched. The prose will suffer because the prose is the least important part of a novel. As long as it's serviceable in describing the plot and fleshing out the characters, it's "good enough".

Lucky for you, there are things like Anarchy Golf.. where you can write Poetry. The plot is unimportant, and there aren't any characters. It's the actual prose that matters. Every letter of every word is important, and the finished product may only be one line of beauty.

So when you get harried from your coding... try some anarchy golf. It's very Zen.
 
If your writing sucked, people would just not read it. Your problem isn't that you're not explaining yourself, it's that you are, and some people don't like what you're saying. (In many cases because they are bozos.)
 
I honestly believe that writing is something we do for every body else and rewriting is for ourselves.
Is an urge to scratch that zone that we know exposes us to others and we judge it harshly from fear.
Anyway, your writing doesn't suck at all, or if it does, is an a way that's soul touching.
Keep sucking!!!
 
Zen Shorts is such an amazing children's book. I always wonder how much my daughter (4) gets out of it, but I get something out of it every time.

Funny how Muth is also the author of 'Stone Soup', another story that is familiar to many through 'The Pragmatic Programmer'.
 
I've often found that in a rigorous code review, anything a maintenance programmer couldn't understand is likely to get all sorts of phantom "problems". The fastest way to get through the development cycle to worry as much about readability up front as workability, and document anything the least bit tricky.

Of course, many organizations skimp on code review, but it does tend to lengthen the testing cycle. Of course, you can skimp on the testing cycle...
 




<< Home
Reg Braithwaite


Recent Writing
Homoiconic Technical Writing / raganwald.posterous.com

Books
What I‘ve Learned From Failure / Kestrels, Quirky Birds, and Hopeless Egocentricity

Share
rewrite_rails / andand / unfold.rb / string_to_proc.rb / dsl_and_let.rb / comprehension.rb / lazy_lists.rb

Beauty
IS-STRICTLY-EQUIVALENT-TO-A / Spaghetti-Western Coding / Golf is a good program spoiled / Programming conventions as signals / Not all functions should be object methods

The Not So Big Software Design / Writing programs for people to read / Why Why Functional Programming Matters Matters / But Y would I want to do a thing like this?

Work
The single most important thing you must do to improve your programming career / The Naïve Approach to Hiring People / No Disrespect / Take control of your interview / Three tips for getting a job through a recruiter / My favourite interview question

Management
Exception Handling in Software Development / What if powerful languages and idioms only work for small teams? / Bricks / Which theory fits the evidence? / Still failing, still learning / What I’ve learned from failure

Notation
The unary ampersand in Ruby / (1..100).inject(&:+) / The challenge of teaching yourself a programming language / The significance of the meta-circular interpreter / Block-Structured Javascript / Haskell, Ruby and Infinity / Closures and Higher-Order Functions

Opinion
Why Apple is more expensive than Amazon / Why we are the biggest obstacles to our own growth / Is software the documentation of business process mistakes? / We have lost control of the apparatus / What I’ve Learned From Sales I, II, III

Whimsey
The Narcissism of Small Code Differences / Billy Martin’s Technique for Managing his Manager / Three stories about The Tao / Programming Language Stories / Why You Need a Degree to Work For BigCo

History
06/04 / 07/04 / 08/04 / 09/04 / 10/04 / 11/04 / 12/04 / 01/05 / 02/05 / 03/05 / 04/05 / 06/05 / 07/05 / 08/05 / 09/05 / 10/05 / 11/05 / 01/06 / 02/06 / 03/06 / 04/06 / 05/06 / 06/06 / 07/06 / 08/06 / 09/06 / 10/06 / 11/06 / 12/06 / 01/07 / 02/07 / 03/07 / 04/07 / 05/07 / 06/07 / 07/07 / 08/07 / 09/07 / 10/07 / 11/07 / 12/07 / 01/08 / 02/08 / 03/08 / 04/08 / 05/08 / 06/08 / 07/08 /