A couple of years ago I heard about this great book about programming called “On writing well” by William Zinsser. The strangeness about this was that it was not a book about programming but a book about writing non-fiction. A book that is great to improve both coding and writing skills? That is too good to be true, I thought to myself.
My curiosity was sky high. Given that I was about to start writing a book myself - Lift Application Development Cookbook - and that I’m always willing to improve my coding skills, I ordered a copy from Amazon and waited anxiously due to slow international shipping rates.
I started to read William Zinsser’s book as soon as I got my hands on it and I was impressed. It was clear: no words laid without intention, no hard to follow sentences.
I grew excited as I advanced through the book. There was something further than the extent of any technical matter: it was like William Zinsser himself was talking to me, teaching me.
As he talked about all the things that makes a good text. Connections between coding and writing began to form into my head and I started to think differently about the code I write.
Is the code I write clear? Can I understand the code I’m writing now? Will this be true in five months? What about in one year? How can I expected people to understand what I wrote If I’m not able to understand it myself?
A coder should not just try to solve a problem, rather, he should try to develop the best solution to a problem. Otherwise, the muddled form of the code still may cause confusion, which in an issue. The best solution to a problem in code is developing a solution that is simple and concise. Making things simple means making our intent clear. Make something concise is not just saying something with fewer words, but more efficiently.
For example, when someone asks: What time is it now? Instead of saying it is 3 minutes past 12 minutes to a quarter to 3 hours past 8 am, which is neither concise nor clear, why not say, “it is 10:36am?”
The same is true about code. Instead of having huge methods and classes doing too much, why not break them into better integrated, smaller, clearer parts?
This is an exercise that requires time and practice and, as writers often revise, they work over and over, changing words and rewriting sentences until they reach a satisfactory result. We programmers should refactor the code we write, changing variable names, splitting methods, moving code around, until we find the code’s intent is clear and it is concise.
William Zinsser says that among those technical matters, one thing that makes a great text, a great story, are the people. A story should be personal.
Think about all the greatest books you have read. They all had interesting stories about people. What people do, how they feel, how they react to what happens to them, these are the things that makes a great history.
Jumping into the code realm, this could mean that a great code is first and foremost concerned with solving a specific problem. The code should be the path from problem to the solution and written in a way that any programmer can follow the story told by the code.
We can say that we have reached our goal if we succeed in writing clear, concise code that solves people problems. Otherwise, we need to keep pursuing it.