A Day In The Lyf

Code that you can read 

Reads like a storybook plot 

Not disconnected

I like to think writing code is a lot like writing a haiku. Haikus have a very rigid structure, and anyone reading one can immediately feel the effect of the structural confines on the poem’s flow. Similarly, code has a strict set of syntactical rules it has to follow that are apparent to even a casual bystander.

However, within the confines of the language, there are still ways to communicate effectively. I know my wife is kidding when she tells me that my job consists of randomly stringing punctuation marks together, and I’ve thought about using her as a test of how readable my code is. She knows (everybody does) that code has to follow rules, and she will not know the rules. But will she be able to at least have an idea of what the code is doing? Will my customers, were I to show them?

As Martin Fowler has noted, it’s actually fairly easy to write code that a computer can understand – the trick is to write code that people can understand. I think showing code to a non-developer is one excellent way of improving in that regard. Show her your code and other code, using different readability conventions, to see which is better. Certain tricks, like using a Ubiquitous Language (see Evans, Domain Driven Design) should help—if you can communicate in your code using the same domain concepts that the end users refer to, then you’re doing well.

But what about abbreviations? I was pairing with a colleague today, and the thing that stood out was that, but for one exception, it was fairly impossible to tell which one of us wrote the code. The one exception was with our variable names. I invariably spelled them out, so I had a DataRow named row, a DataTable named table, and a domain-specific type MercedesMonthlySummary named month. For the same types but in different methods, my colleague had dr, dt, and mms.

I’ve seen code written by far better developers than me that used abbreviations where I would have preferred an English word, so it’s hard to discredit them. Developers get used to it, and certain abbreviations (like dt for a DataTable) become commonplace. And still, I can’t help but think that we’re losing our expressiveness when we use them.

If you don’t believe me, show your code to your wife, and see what she says.

Code that you must read 

dr dt mms 

Someone understands?