On Writing (Code) Well

Following an advice from Cyrille Martraire, I just finished reading On Writing Well: a non-fiction guide written 35 years ago. Reading this book helps me to realize there are lots of similarities between writing code and non-fiction.

The arrogant guy

“A simple style is the result of hard work and hard thinking. A muddled style reflects a muddled thinker or a person to arrogant, or too dumb, or too lazy to organize his thoughts.”
– On Writing Well, William Zinsser

I like this quote because who has never met a codebase much more complicated that what it needs to be? I was one of these arrogant guys not so long ago.

I was proud to write code that none of my co-workers can understand. It took me a while to accept that my code was bad, and that I overcomplicated it in order to look smart. It took me a while to realize that I had a muddled style.

Rewriting

Another similarity is that it’s more about re-writing than about writing. No writers are able to produce a perfectly understandable story at the first shot. They have to write, and re-organize, and change, and remove things until it is clear enough to be shared.

Refactoring seems absolutely normal for a writer. But for a software engineer, we expect a perfect code at the first try.  We’d like to believe we are so smart that we can build a whole business process in our mind, and write it in an unambiguous way for a computer who doesn’t speak our natural language. But we can’t.

Decreasing the cognitive load

We need to decrease our cognitive load, to focus on the really tiny portion of the whole business process we want to manage. Being able to reason about our code is paramount to high quality. And we can’t reason about our code if our brain is full of things unrelated to the problem.

In the same way, non-fiction writers can’t write a good article if their brain is full of things unrelated to their topic.

Feedback

I see one big difference between writers and coders though: feedback loop. When writing non-fiction, it’s hard to know if your content is good before releasing it.

As developers, we have a very quick feedback using automatic unit tests.

The developer/writer metaphor

The house building metaphor hurts a lot our industry.
I think a better metaphor would be that writing software is like writing a book.

It’s something to remind our managers next time they want to add writers to solve our deadline issues.

Writing software is like writing a book with several other people, during several months, if not years.