Code should be clean.
If you’re the only person who will ever see your code, make it as hideous as you want. You’re only punishing yourself.
However, if you ever plan on sharing your code with someone else (e.g. your public GitHub when applying to a job, a project with a team, or a project of your own after an extended period of time) then you want your code to not suck. Just because it works doesn’t mean it doesn’t suck. Even “optimized” code can be bad.
These ten rules are not every rule ever, but they will help you become a much better team player and a much cleaner coder.
1. D.R.Y. — Don’t repeat yourself
This is first because it’s a classic. Everyone should know it. Don’t repeat yourself. If you’re repeating code, you’re inherently being inefficient (and creating opportunity for bugs). Repetition means there’s an opportunity for abstraction, looping, recursion, etc.
2. Names should be self explanatory
Scenario: you’re creating a variable to hold the number of login attempts a user has made. What would be a good name? If you answered something along the lines of numLoginAttempts, you win! If you name your variables any variation of num, numLog, or (God help us) num1, try again.
Method names should be just as obvious, and ideally follow a verb + “thing it returns or does” pattern. That means opensNewPage should open a new page. A method called getRandomNumber should get a random number. Nothing more, nothing less. Not a random and mutate the original value within the method. Not pushing that random number into a pre-existing array. Just getting it.
3. Name as specifically as possible
You have a user model with a field “age.” Is that the user’s literal age? Their account age? A boolean to discriminate if the user is over 21? An acronym?? Name specificity avoids this kind of problem.
4. Use consistent conventions
Teams often have conventions for how they name their commits, variables, props, etc. Learn what they are, and keep them as best as you can across the ENTIRE codebase. Keeping conventions means you learn the codebase faster and identify problems more easily.
5. If your code isn’t obvious, add comments.
Sometimes, you have to write a complex function or class. “Complex” in this context means it’s not immediately obvious how it works. That’s okay. People have different opinions on comments, but the bottom line is it’s better to have comments that provide clarity to your work than to try and be succinct and clever with your code at the cost of creating something no one else can work on in the future. That’s being an unhelpful teammate.
6. Remember the bus test
The bus test isn’t just a coding thing, but its value is absolutely critical in software development. “If you got hit by a bus tomorrow, could someone pick up and maintain your code?”
What does this have to do with clean code? Isn’t it mostly about cross-training your team? It definitely has to do with cross-training, but because new code is (ideally) being added every day, then unless your team pair-programs every day, there is code in the system only 1–2 people know.
Writing clean code means you’re not screwing over your team when you call in sick, go on vacation, or lose your passport and get stuck in Amsterdam for a week.
Does your code actually make sense to someone who didn’t spend a few hours thinking about and writing it? Because it doesn’t matter if it’s an “optimal” solution if no one else can understand it.
7. Make small commits
Smaller commits means quicker review, fewer mistakes, and tighter abstraction.
8. Branches should be only addressing ONE feature at a time
This doesn’t mean one file, but one concept.
Let’s say you’re changing a menu to offer four options instead of three. You need to change the frontend UI, an API endpoint, and a database structure to account for all of this. Great, that can all fit on one branch.
What does not fit in this hypothetical branch is a quick change to the navbar color. Even if it’s “just one line of code” and you don’t want to make a whole new branch just for that one minor change, don’t do it.
When you muddy up your commits, headaches happen. Eventually someone will revert a change thinking they know what they’re affecting, and they create a problem that takes them hours to troubleshoot because branches and commits weren’t appropriately separated.
9. Have someone else review and merge your pull requests
Someone else reviewing your work will catch dumb mistakes, suggest better ways to implement your changes, and everyone will align on the work you’re actually doing, creating familiarity with the overall code base.
10. Use a linter before you commit anything
Automating your formatting means less human error (and not having to hunt down formatting changes to make). Even better, you can set up your CI pipeline to automatically lint any submitted code.
Clean code is a habit and you build it over time. If you’re someone who prefers simplicity, you’ll like clean code. If you like complexity, this might be more of a challenge. If that’s you, don’t worry! There is still plenty of complexity to be had — just don’t make your code quality part of it.
This blog was inspired by Clean Code by Robert Cecil Martin (AKA Uncle Bob). Great read if you want more.
If you want more from me, I tweet dumb jokes and love a good conversation.