If programming were a recipe, how would you know when the dish is ready to be served? When it’s working, right?
Along with the wolf, we howl “Not at all, we’re not finished yet”. Indeed, apart from working, now you have to make the code attractive for the human eye. You have to make it clear enough for a human to easily read it, and change it when the need comes.
Make the change easy, then make the easy change.
Kent beck
As good as it gets
But then, how do we know when our code is “good enough” to commit it?
When you’re simply writing, say, a blog post, good enough is usually a consequence of caring about:
- The message you’re trying to convey.
- Making the message understandable and entertaining enough for the reader to keep reading until the end.
This “good enough” thing is not trivial when programming. While coding, initially you first find these two layers of immediate urgency:
- Making the compiler happy.
- Achieving the desired business logic.
Once you’re past those, our job is done, right? All together now, let’s howl with the wolf:
Of course, we’re not done yet. So far, we have only a draft, and we shouldn’t publish/commit a draft.
The “Kissinger standard”
You can try the best you can, the best you can is good enough
Radiohead
Henry Kissinger once made someone write a report for him. Once the report was on his desk, Kissinger called the writer to his office.
-Is this the best you can do?
The writer’s look went down from Kissinger’s inquisitive eyes to the report. Without saying a word, he slowly grabbed it and left the room.
He rewrote it and sent it back to Kissinger.
Kissinger called him back to his office.
-Are you sure this is the best you can do?
The writer, once again, took his report submissively and left, once more, to rewrite it.
The same scene occurred several times more until the writer, near to desperation, finally told Kissinger:
-Mr. Kissinger, yes, that’s the best I can do, I don’t know how I could make it any better.
And that’s when Kissinger retorted:
-Great! Then, I’ll start reading it…
We’ve all met people that commit code that is only their first working draft. They’re only worried about going fast. And going fast today usually means… going slow tomorrow. And that compounds until one day you can’t even move. Going naturally fast comes only after aiming at our dear old friend, “good enough”. And “good enough” is to have in your mind that “Kissinger standard”.
Developing an eye
Perhaps what all of this boils down to in the end is just a matter of aesthetics. Some people have it naturally and others (most of us) need some effort to develop it.
How could a programmer, working alone, have that inner Kissinger who’s continually asking Is this the best you can do? That’s why developing that aesthetical eye is more likely to happen quicker when coding together with other people, either with pair or mob programming. That immediate feedback you get in those occasions is gold for a software writer.
If, for whatever unfortunate reason, you can’t code together with other people, take David Heinemeier Hansson‘s advice to develop that “eye”: read and write lots of code; and, more importantly, rewrite even more.
The only kind of writing is rewriting
Hemingway
Of course, we should never forget context. We should also ask ourselves: “How long is the code I’m writing going to last? How often might it change?”
If you’re doing exploration, for instance writing some code for a POC (Proof Of Concept), perhaps you don’t need to spend that much time rewriting when you’ve already get to the certainty/knowledge/whatever you were looking for.
But, as a rule of thumb, when in doubt, the only way of nailing it is not to publish the first draft. Rewrite, then rewrite again and finally rewrite some more. Until when? Until you have done enough rewriting… This is, whenever you get to a point in your mind in which the more frequent answer to the following question is “no”:
“will the reader have to do some unnatural effort interpreting what I’m trying to do here?“
Let the computer do the effort by computing the code. Let the reader understand you easily by making your intentions clear. Be honest. Be direct. Build the path to human understanding in your code. Tell the story, make it obvious.
No excuses
A great chess player once said, “whenever you think of a good play, rethink of a better one”. A working draft is always necessary at first. But it’s just a station on the route, not the destination. A false sense of speed can tempt us into thinking that we’ve crossed the finish line and publish the code. Don’t. Patience and rewriting to the rescue.
But, wasn’t perfect the enemy of good?, some might say. And I would agree with them to a certain extent. But publishing a draft is even a greater enemy of good than perfection is. And, just in case you’re thinking of agility: committing a working draft is not agile: it’s, simply put, sloppy. If you can do it better, just do it. No excuses there. Be a good software writer. Write “good enough” software. Your readers/cowriters will appreciate it.
