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.


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.


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.

continious-feedbackThe 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.

A Craftsman work-life balance

I don’t feel comfortable when I hear people explaining how hard we should work to be “successful”. Mainly because “success” is subjective, it only makes sense in a given context.

For example, Uncle Bob in The Clean Coder asserts that a professional developer must work around 60 to 70 hours per week. 40 hours for his job, the rest of the time to improve his skills.

I deeply respect Uncle Bob, but when he says that I must dedicate 3 hours per day, week end included, from my personal time to improve my craft, I definitely not agree.

Professionals have a personal life

We are valuables professionals with a really limited resource: time.

A company does not own 100% of our time because it fills a pay check. We don’t sell our lives, we sell our skills for a given period of time.

Investing on these skills is important. Learning new things is important. But it is unsustainable to do it only on our personal time. And when it’s done during our personal time, there are different things that can be done to keep an enjoyable life.

cat on beach

How to learn at work and stay efficient?

We can learn new things at work. Of course it does not mean we can play all day long with the last shiny technology when it produces no value for the company.

But we can do pair/mob programming. Whatever the job and the level of the co-worker we are pairing/mobing with, we will learn a lot of unexpected things.

We can explore new languages/tools on tiny internal topic. During a limited time (half a day? A few days?), we can pick an internal subject (improve the deployment script?) and try to solve it using an unknown tool/language we like.

It’s possible to organise 1 hour katas once a week. Or maybe to watch an interesting talk during lunch?

We can also switch a few people in the team on a regular basis. It will reduce the bus factor and spread good practices through the whole company

How to learn at home and keep friends and family?

When we think about it, we tend to realize there are lots of time we don’t use efficiently.

Work commuting is a good example. This travel time cannot be reduce. We can use it to read a book about the last subject we’d like to learn about. In car it’s possible to listen for audio-books or podcasts.

Waiting queue is another example. We wait a lot for: a plane, a train, a meeting, a doctor… It’s easy to keep a book, or better, a pdf on our phone to read instead of passively lose our time.

For sport addicts, what about listening some podcasts during the workout? It is true multi-tasking: the brain can listen to the podcast when the muscles are working on something different.


A crafstman work-life balance

I believe a good work-life balance is essential to be a software craftsman.

Personal life matters, it is the pillar to build a strong professional career. Not the other way around.

If people believe that they have to work 70 hours a week for their whole life to be professional, who will ever want to commit for a life career as a software engineer?