I recently started a new job. With every new job comes a new codebase. This is probably my twentieth job. So I’ve seen a lot of codebases.
Unfortunately they all suffer from the same fundamental issue -inconsistency. Likely the result of years of code patching, large teams, changing hands, or all of the above.
This creates a problem becausewe read code far more than we write code. As I read a new codebase these inconsistencies distract me from the true code. My focus shifts to the mundane of indentation and variable tracking instead of the important business logic.
Over the years, I find Iboy scouta new codebase in the same way. I apply three simple practices to clean up the code and improve its readability.
To demonstrate, I’ll apply these to the following, real-world code I read just the other day.
I know I’m the 1,647th person to say,“format your code”. But it apparently still needs to be said. Nearly all of the codebases I’ve worked on have failed to adopt a code style. With the availability of powerful IDEs, pre-commit hooks, and CI pipelines it requires virtually no effort to format a codebase consistently.
If the goal is to improve code readability, then adopting a code style is the single, best way to do so. In the end, it doesn’t matter which code style you adopt. Only that you apply it consistently. Once you or your team agrees upon a code style, configure your IDE or find a tool to format the code automatically.
Here’s the same code after adopting a code style. The indentation allows us to see the structure of the code more easily.
Yes, something else you’ve heard plenty. I knownaming things is hard. One of the reasons it’s hard is there are no clear rules about naming things. It’s all about context. And context changes frequently in code.
Use these contexts to draw out a name. Once you find a clear name, apply it to all contexts to link them together. This will create consistency and make it easier to follow a variable through the codebase.
Don’t worry about strictly using traditional naming conventions. I often find codebases mix and match. A clear name is far more important than
camelCase. Just apply it consistently within the current context.
If you’re stuck, use a temporary name and keep coding. I’ll often name things
$whateverto avoid getting on stuck on ahard thing. Once I finish coding the rest, I go back and rename the variable. By then I have more context and have often found a clear name.
Clear names will help future readers understand this code more quickly. They don’t have to beperfect. The goal is to boost the signal for future readers. Maybe they can incrementally improve the naming with their afforded mental capacity.
After analyzing this code, I have more context to choose clearer names. Applying clear names not only improves readability, but boosts the context making the intent of the code easier to see.
There are some hard rules regarding nested code. Many developers believe you should only allow one nesting level. In general, I tend to ignore rules with_hard_numbers. They feel so arbitrary given code is so fluid.
It’s more that nested code is often unnecessary. I have seen the entire body of a function wrapped in an
if. I have seen several layers of nesting. I have literally seen empty
elseblocks. Often adding guard clauses, inverting conditional logic, or leveraging
returncan remove the_need_to nest code.
In this case, I’ll leverage the existing
returnstatements and flip the
switchto remove most of the nesting from the code.
In the end, coding is writing. As an author you have a responsibility to your readers. Maintaining a consistent style, vocabulary, and flow is the easiest way to ensure readability. Remove or change these and maintain readability you will not.
Want to see these practices in action?I’m hosting a free, one-hour workshop where I’ll demo each of these practice, and more, through live coding.Sign upto secure your spot.