Readable Code

I've been working as a developer a good number of years. During those years, I have seen my share of good code and bad code. Some of it written by myself (good and bad I might add...). But we learn from our mistakes, and eventually principles, dos and don'ts gets integrated into the way we code, hopefully into something great.

I still struggle somewhat with analysis paralysis, but my best remedy for that is to go back to the core of agile and focus on what is needed right now. TDD helps a lot as well. Agile practices are great for keeping the code slim and to the point, but that alone is not enough for producing good code. So I'd like to spend some time writing a bit about what I think good and bad code looks like.

First, I believe code should be written as prose, with the primary intent that other humans should be able to easily read and understand it. The reasoning is that code is read a lot more often than it is written. This simple sentiment makes it obvious that code must be easy to digest, so it is worth spending some time now making your code readable, to save lots of frustration later. I loathe having to read and re-read the same code chunks again and again until I understand what it does, only to realize I was looking in the wrong place and have to go search somewhere else to fix it.

Clean, readable code is a joy to read and it serves as good examples for others as well. Programmers, especially juniors, learn a lot from reading code and it is natural to mimic existing code. This means that good code breeds good code and, unfortunately, the same is true about bad code.

These are my priorities when writing code:

1. It should work correctly.
2. It should be clean and readable.
3. ...
4. If needed, optimize for performance.

Lets start this with my favorite coding guideline: Write readable code instead of comments.

Agile Value #2: Keep Documentation Light

Let's look at the next core agile value.

We value working software over comprehensive documentation

No amount of system documentation can compensate for a non-existing system. We can spend the better part of a projects life time writing specifications, discussing use cases and drawing designs charts without actually producing anything truly valuable for our customer. Working software is always more valuable than documentation and that is always the way we measure progress.

Not all documentation is bad, just that most of it is not really needed, and it is tedious to keep in sync with the actual software. Also, when documentation and implementation does not agree -- who is right?

Requirements

The classic requirements document is created through sweat, tears and lots of frustration. Frustration because it is a document predicting the future. If we predict the future wrong (which we will), it will inevitably cost us money, trust and maybe our jobs. Nothing good can come from this. 

Instead, things planned for the future should not be detailed at all and stuff that is nearer should be fleshed out more completely. When it is time to implement them, we should spend more time detailing them. This is the moment when we have as much information as possible, but not before that. This is called the latest responsible moment.

One way to think about it, is to imagine that you have all planned features laid out in front of you, from your feet towards the horizon. Items that are closer to you is more important right now and are seen clearly with details and everything. Things further away are a little blurred and only the title and some text is readable. Things even further away are so blurred that it is not possible to make out any details except the headline. When the nearest items have been implemented and the next features are shifted towards you, you can see them more clearly and you notice they are lacking crucial information. Now is the time to add more details.

Systems Documentation

Scrum and XP is based on the core agile values which is about preferring collaboration and working software before documentation and tools. It means that your time is best spent creating a shared understanding of the system design rather than writing detailed documentation. For this to happen, the team must talk about the design all the time; how to make the design better and how to adapt it to new changes. Constantly. All members in the team must be involved in the design discussions. Here are a few pointers:

• Don't write any systems documentation unless you have working code. Defer any such efforts until you have delivered your first incremental release. And as always, keep it simple!
• Draw an outline of the system so the team can easily to see how different parts are connected. This is the overview and should be pretty stable over time. Keep it up prominently on a wall.
• Locate your most important entity in your system (Order, Blog Entry, Transaction, ...) and create a state diagram for it. I have noticed that having the team create a few state diagrams helps their understanding of the system and they may even find a few quirks or bugs. Once the system starts growing, add one or two sequence diagrams showing a typical "request" through the system.
• Readable code without comments is what we are aiming for. It is much better to write clean code than copious amounts of documentation.
• I recommend adapting a mentality that considers every comment in the code as a personal challenge: Can I rewrite and clarify the code so the comment is not needed anymore?
• Use refactoring techniques with unit tests and don't be afraid to use longish function and variable names to make things clear.
  

I am going to write more about comments in a later post, so I'll leave that for now.