Tuesday, September 18, 2018

Readability, an Essential Code Quality

Readability is an important code quality.

In fact, it is absolutely-critical. If a team can't understand the code they maintain and extend, then they can't really maintain or extend it.

That's just the difference between "some readability" and "no readability". While it's possible to create inscrutable code, it's more common to write code that is difficult, but not impossible, to understand.

The consequences are still dire.

One way that it can hurt a team is when they try to scale. A new developer can start to work with well-written code fairly quickly and with a low investment from existing team members. On the other hand, I've seen code that was so difficult to understand that a team was unwilling to take on new members because it costs too much time to hire and train one.

Think about that. You're strapped for time. You're always under the gun. You need more people. Yet the cost of acquiring more talent is so high that you can't bring them in and get the help you need. It's a textbook vicious cycle and the way it resolves is not pretty.

There's a still-more-basic consequence of not paying attention to readability: you might fail the Future-Self Test and not realize you've done so until it's the future. If you don't maintain the readability of your code and there is any gap in your maintenance of it, you become that new team-member who is completely befuddled by the source and the cost of working with it skyrockets.

There's no magic way to keep code readable. You just have to be vigilant.

Here are some techniques that make it a little easier:
  • Automate the dumb decisions (e.g., let your IDE manage indentation)
  • Pair or do regular code reviews
  • Apply the Future-Self Test whenever you can