Core Developer Skills: Code Qualities: Readability

Recommended Book

  • McConnell, Steve. Code Complete: A Practical Handbook of Software Construction. 1993.
Provide Feedback

Any reasonably experienced software developer should be able to read your code.  There are numerous techniques you can use to ensure this.  Adhering to a coding standard, using meaningful, intention-revealing names for state members, methods, classes and all entities in your code, and paying attention generally to the readability of your code is essential and not particularly difficult to do.

For example, creating consistency around issues such as this:

public void getTaxes() {
 // implementation
 }

vs.

public void getTaxes()
 {
 // implementation
 }

…seem trivial distinctions as first, but over the long haul of complex projects can introduce significant confusion, and impede teamwork. At Net Objectives we don’t suggest a particular coding standard as “best”, but rather emphasize that the best coding standard is the one that everyone adheres to, whatever it is.

Generally, if your code has an excessive number of comments explaining what it does, your code may not be readable enough. We prefer method names and signatures that, in and of themselves, communicate what a comment would. The compiler, after all, does not check your comments.

Benefits

Readability has an obvious benefit and a subtler one.  The obvious benefit is that, people who can understand your code can maintain your code.  The subtler benefit is the impact that thinking about readability has on design.

Easier maintenance

Widening the set of people who can read your code widens your pool of potential maintainers.  Most frequently, this manifests as groups of people being able to modify code rather than individuals who each own their own personal “silo” of code.

Readability also reduces friction when making changes.  The less time you spend scratching your head and staring at a screen, the more time you’ll be able to spend doing what you actually ought to be doing.

Better design

The subtler benefit of a readable and understandable codebase is that certain readability-improving activities also force your design to be better.  For instance, making sure a class or method has a meaningful and correct name provides some feedback on the design.

Is the name too long?  Maybe cohesion could be improved.  Is the name bordering on techno-babble?  Maybe you’re building a framework where you should be building to needs instead.  Et cetera.

Obstacles

The obstacles that stand in the way of readability tend to center around team structure.  Here are a few examples…

You can’t agree on how to describe something

Sometimes two or more parties will want to describe a concept differently.  This can manifest as anything from wanting to name a method differently to wanting completely different designs.  The cause can be anything from stubborn pedantry to a genuine disagreement on the nature of the concept being codified.

You can’t agree which of two designs is more readable

Sometimes you will have multiple possible designs and, regardless of whether or not everyone agrees on how descriptive they are, people won’t be able to agree which is more readable.  Sometimes this comes from two people just plain wanting to recognize design forces differently.  Sometimes it comes from someone not understanding the design they think is less readable.

Solutions

People- and analysis-problems are hard to solve.  They are especially hard to prescribe solutions for in writing because they tend to have a vast array of potential driving forces.

Notwithstanding the kinds of problems that arise from stubbornness or personal preference, here is some general guidance:

Differing descriptions might mean different understandings

If two people want to describe something differently, that could be a sign that they are describing different things.  In that case, either zero or one of them is right.  As a team, you should investigate these kinds of disagreements and use them to improve your understanding of the problem you are addressing.

Different assessments of readability might mean different levels of skill

Sometimes, people just have different preferences.  Other times, one person understands how to solve a problem differently than another.  In that case, make sure you investigate and upgrade the team’s skills as needed.

You might need to change course

If, as a team, you are regularly experiencing significant difficulty writing code that everyone agrees is readable, you might need to take a step back and think about what you are doing.  Is there a fundamental assumption you missed or got wrong?  Is there a basic concept that isn’t recognized in your design?  Maybe not but it’s best to find out early if there is such a problem.