PMI Sites
Register
Disciplined Agile
Search

    Core Developer Skills: Readability

    Any reasonably experienced software developer should be able to read our code. There are numerous techniques to ensure this. Adhering to a coding standard, using meaningful, intention-revealing names for state members, methods, classes and all entities in our code, and paying attention generally to the readability of our 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. 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 our code has an excessive number of comments explaining what it does, our 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 our comments.

    Benefits

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

    Easier Maintenance

    Widening the set of people who can read our code widens our 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 we spend scratching our head and staring at a screen, the more time we can spend doing what we ought to be doing.

    Better Design

    The subtler benefit of a readable and understandable codebase is that certain readability-improving activities also force our 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 we are building a framework where we should be building to needs instead.

    Obstacles

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

    We Cannot 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.

    We Cannot Agree on Which of Two Designs is More Readable

    Sometimes, we 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, we should investigate these kinds of disagreements and use them to improve our understanding of the problem we 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 to investigate and upgrade the team’s skills as needed.

    We Might Need to Change Course

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

    May 2023

    Core Developer Skills Overview