Why Most Code Sucks
And what you can do to improve yours
Sorry, I didn’t mean to be this rude. It sounds kinda harsh, doesn’t it? But the thing is, there’s a grain of truth in it. You’ve probably looked into some codebases and thought that they were a complete mess.
No developer is perfect. All of them, no matter how good you think they are, have made mistakes, both small and big.
Poor naming, functions that are way too big, poor architectural decisions, duplicate code. I could continue adding to this list for quite a while, but you’ve probably seen all those mistakes.
Either you made them yourself and someone pointed a finger at you or you had the honor to look at a pull request from some other developer.
In this piece, we’ll go over how you can reduce the chaos in your codebase and make it a better place.
The Reason Most Code Sucks
Good code meets certain criteria. It should be readable in the first place. One of the reasons most code sucks is that it’s hard to read.
Readability of code is such an important factor because you’re probably not the only developer working on the project. And even if you were, would you still remember the entire codebase after a year?
To improve the readability of your code there are a lot of things that you can do. One of them is giving meaningful names to your variables, methods, and classes. Yes,
elapsedTime is a decent variable name, but how about
elapsedTimeInSeconds? That’s just so much more meaningful.
Use pronounceable names that reveal their intention and avoid misinformation. Knowing how to give meaningful names can make it much easier to understand a piece of code, and therefore easier to maintain.
Try to keep your functions short, so they will stay readable. This will also make your functions much more understandable. A hundred-line function that does three different things is not what you want. To keep them short, your function should do one thing. And one thing only.
Another good practice to keep your code readable is to keep a limit to the number of indentations. Code tends to get much harder to read when there’s too much indentation.
Instead of using all sorts of nested
if else constructions, you could use guard clauses. This will help you keep a limit to the number of indentations that are needed.
Also, avoid using one-line wonders. Readability is very important, and you should not sacrifice readability to get less code.
Keep in mind that code gets read much more often than it gets written. Robert C. Martin said the following about readability:
“We are constantly reading old code as part of the effort to write new code. Therefore making it easy to read makes it easier to write.” — Robert C. Martin
“You need to write code that minimizes the time it would take someone else to understand it, even if that someone else is you.” — Dustin Boswell & Trevor Foucher
Code can be readable, but still not easily understood. Take the quirky one-line wonders as an example. Sometimes code may read well, but it still can be misleading.
To make it more understandable, you could add comments. Although well-written code might eliminate the need for comments to explain what you’re doing, you could still choose to add comments that explain the why.
Comments that explain why could be extremely useful once your project enters the maintenance phase. Which brings us to the next reason why most code sucks. It’s not maintainable.
You’ve probably worked your ass off to ship the project to production just in time. To finish before the expiration of the deadline, you probably made some sacrifices. Although it’s not desirable, it is understandable.
As a result of the sacrifices that you’ve made you’ve introduced a new, significant problem. One that costs you a lot of time. A requirement that has changed, that normally should take you only a few lines of code to fix, now takes you a couple of hours because you have to rewrite a part of your code.
You’ve sacrificed maintainability.
And the funny thing about maintainability is that it’s easier to recognize by its absence. Roughly speaking, maintainability is inversely proportional to the amount of time it takes a developer to make a change and the risk that change will break something.
One of the reasons that things break in code is because of duplication. For some (bad) reason duplicate code sometimes sneaks into the codebase. Most of the time this will go hand-in-hand with new bugs that also sneak into the codebase.
There is a danger that one piece of code gets changed and its duplicate equivalent gets forgotten about. This results in new bugs that get introduced. This happens way too often. If you want to make your code better you should avoid duplicate code. At all costs.
Duplicate code can be fixed most of the time by moving the code into its own function or class. And then call that function or class from all of the places where it was originally used. It is a pretty simple fix that will save you a lot of time in the long run.
The last reason most code sucks is that it isn’t testable. There’s a pretty easy explanation for this. Most programmers don’t like testing, at all.
Add the fact that way too many programmers lack the skills to write proper tests. Or know how to write tests at all. The combination of these two things is bad.
See how they both keep each other alive? If you don’t know how to write tests for your code, you probably also don’t know how to write testable code. And as we all know, it’s naive, at best, to not test your code.
But how do you make your code testable?
Testable code is code that’s written in such a way that it is independently verifiable. Testable code receives dependencies as input parameters so that fake dependencies can be injected during testing.
It is good practice to keep the number of code paths in a method small so they are straightforward to test. If you plan on writing unit tests every code path should be touched. This means that every code path probably has its own unit test.
Well-written code meets certain criteria: it is readable, understandable, maintainable, and testable. If code doesn’t meet these criteria, chances are that it sucks.
There are numerous ways to improve the quality of your code. One is easier to implement than others. For example, making your code testable can be much more work than removing duplicate code.
Just know that every developer makes mistakes and that it’s never too late to fix them!
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.” — John Woods