Telling a Tale of Code

When we become experienced developers there is a subtle change in how we read code, we stop necessarily reading keyword by keyword, variable by variable.

Instead were able to recognise prose we've seen before and appreciate the story being told whether good or bad.

Our ability to do this is dependent upon the care that is taken in trying to tell the story.

An often quoted mantra is "Good code doesn't need comments", while it would be a slightly extreme view point to never write comments its certainly true that good code is readable code and there are certain techniques we can use to maximise this readability without the need of explanation.

Whats In a Name?

All good stories need well defined characters, a skilled author is a master of nouns and verbs, clearly the name of a variable should convey what is being stored and a function should describe what action it will perform.

What can be more subtle is that in neither case should we be describing the how, a variable name shouldn't talk about the underlying data structure and a function name shouldn't expose detail about implementation. For example should a method be called saveToDatabase() or just save()?

Details change and unfortunately there is no inherent mechanism to keep our variable and method names in sync. One form of unreadable code is where you simply cannot tell what is going on, another just as destructive one is where you think you know but the reality is very different.   

Paragraphs and Chapters

No matter how skilled you become at reading code there is a limit to how much code you can interpret in one go.

Another approach to things like the Single Responsibility Principle and Interface Segregation Principle is that they limit the required scope of understanding of the reader.

By dividing and conquering we make our code more readable and understandable because their is less action on the page and less to get our heads round.

Logical structure also means we can take much more as read, if your injecting a dependency called IPersistentStorage that has a well defined CRUD interface I have no need to look into the detail and I don't need to understand anything more than what is on the page.  

Clear and Consistent Voice

In a similar manner to having a logical structure having a clear and consistent voice when writing code will also go a long way to helping others understand your story.

This means a common approach to naming, using similar solutions for similar problems and ensuring that a common plot is running through the whole story.

A common problem when looking at large open source projects is that many people have been involved in its development, each with a different story to tell and a different style and approach.

Individually all these different voices may be clear and logically but when there all layered over each other it suddenly becomes confusing. Navigating around the code base suddenly feels like different chapters from different books.

In many of these situations it doesn't really matter what you do, just always do it that way.

A large amount of comments in a code base is a slight smell, whether its because the writer feels you may not understand this bit or because they want to draw attention to there genius it implies the code itself is not well structured or logical.

This becomes even more prevalent as the code base evolves as the comments get more and more out of date with the code there supposed to explain.

There will be occasions when you really are forced to do something that requires explanation but ultimately nothing is more expressive than the code itself after all its this that defines what the story is and how it will end.