Thinking > Writing > Writing Code > ??? > Working Software
The business benefits of writing readable code
Good code reads like prose. It tells a story. You learn something about the system by reading it.
Bad code reads like a maintainer’s guide for a 1980’s espresso machine without speaking Italian.
Code ends up being read 10 times more than it takes to write it. You thought rewriting your entire project takes a long time? Try re-understanding it!
The value proposition is simple. Easy to read code gives you the following benefits:
Changing features is faster
Adding new features is faster
Onboarding new engineers is faster
Finding bugs with up-front design and analysis is easier / made possible
Bugs are easier to prevent
Bugs are easier to fix
There’s one thing well-written existing code doesn’t help with. Exactly the thing engineers do to avoid working on a project with bad code.
Setting up a new greenfield microservice.
The Writing Process and Code Reviews
Larry McEnerney summarises it perfectly (video below):
“You are using your writing process to think.”
The first draft of a book sucks. It’s really bad. That’s why it gets pre-read, reviewed and edited.
Code reviews do the same thing for your code.
The first time code is written it is the developer’s process of understanding how to write it.
The purpose of refactoring, following TDD and XP is to re-write your code immediately after gaining that understanding.
When your first draft makes it to the mainline branch, and worse —production— that’s when the nasty bugs happen. Not just for the author. Everyone involved with reading and understanding.
Because the original thinking and understanding process were lost. Discarded. And they have to be re-done in order to fix bugs. Even when it’s a one-liner. It may take more time than writing the entire feature.
Successful businesses adapt. Rigid ones go out of business
I interviewed Jason Gorman last year.
This quote stuck with me as a beautiful encapsulation of writing code:
“Code that gets used tends to get changed.
If you are intending for your code to be used, you should be planning for it to be easy and safe to change.“
And what makes your code easy and safe to change?
Making sure it is easy to read.
And you don’t have to figure this out on your own. There are tools to help you.
Codescene actually does this automatically for you. It highlights hotspots for you where code changes often. Code that went through many hands, many ideas and probably has some skeletons in the closet.
Those components, files, packages are generally the dirtiest. Unless you make sure they aren’t.
Not DRY - WET - Write Everything Twice
Changing how the code is written without changing its behavior is refactoring. When adding features haphazardly your team may be refactoring parts of the code to be harder to read. The deliberate act of making it easer instead is the process of removing code smells. The book clean code covers this, as do many others. However, it’s quite opinionated and specific to languages like Java or C# and I won’t bore you with the details.
Here is an example from Codescene a tool that detects these code smells for you automatically.
Red Flags
Addressing these three red flags will immediately make a large shift in your engineering efforts:
Code that has less than 1 maintainer (0 if the author left the company)
Commits with large changes and large complexity (Things are getting worse and no one is reducing complexity)
Areas of your code with large commit frequency (this is where the confusing bugs are)