Code Maintenance Part 2 — The What
Hopefully you are convinced about the Why of code maintenance. If not, please check out my first article in this series.
Let me now focus on the What.
What are the types of Code maintenance?
Broadly, there are two types of maintenance: Preventative and Reactive.
Preventative maintenance
Preventative maintenance is trying to avoid code smells, bugs, and down times. It’s about setting up guard rails so that you and your teammates do not fall. It’s also about thinking ahead — scalability, modularity, maintainability, and future requirements. This is often the difference between code written by amateur and a professional.
Following are some of the preventative measures you must take up:
1. Set up code linting
This is usually the first thing I do when I start working on a project. It’s a very easy thing to do and it delivers so much value. This brings in readability, code standards, consistency, and avoids obvious errors and code smells. By setting up code linting, you are removing personal bias of developers and also delegating the most mundane tasks to your linter.
2. Set up unit tests
No one will write any tests, if there is no test setup. Once you have a setup, have some reference tests, coverage report, etc. then it is likely that developers will contribute to more tests. Also, writing tests forces a developer to think of all the edge cases. In the long run, it avoids regression bugs and gives you confidence while you do large refactoring.
3. Automate your pipelines
Deployment should be an easy and predictable task. Every developer should be able to confidently push a code to production. Set up PR checks, run linting and tests in your build, use code scanners and automate your database migration scripts.
If a bug gets pushed to production, it’s not the developer’s fault; it’s the team’s failure in setting up appropriate guardrails.
4. Setup dedicated time for code maintenance
This is probably the most important measure you can take for code maintenance. Treat code maintenance as a first-class citizen. Setting up dedicated bandwidth for it will force you to take inventory of your software. It will give you time to update readme files, update libraries, and clean up the recently created mess while it’s still fresh in the minds of the developers who created it or reviewed it.
Reactive maintenance
Sometimes you can try and take all the preventive measures to maintain your code but then reality hits you hard and you still find yourself in the stinky mountain of bugs and code smells.
Why does code get messy?
1. Requirements changed/grew over time
This is the most common reason why code gets bad. You thoughtfully design and build a feature and it’s all pretty. Then requirements changed, maybe the scale changed and you made multiple changes to ensure that things continued to work.
At some point, you stopped thinking about, “How would you design this?” and started thinking, “How can I make this work in the current architecture?”
2. Hotfixes and hacks
We’ve all done it. There was an urgent fire in the production environment. The stakes were high, we got in and got the job done. All that we cared about was putting off that fire.
3. Inconsistency in code, designs & UX
You made something. Your colleague made something different. It didn’t seem like a big deal and you didn’t want to argue. And then it became an acceptable thing to do, and as a team all of you have collectively lowered your standards.
4. Dependencies
You were using a third party library or a package as your dependency. It got updated and it broke your code! Or your colleague started using another library and together they do not work well and/or are redundant.
5. Legacy decisions by previous developers
People switch projects and jobs. Sometimes you forget to document your decisions, give KTs and communicate your design reasons. And when you are handed someone else’s code mess, you do whatever you can to make things work and don’t ask too many questions.
Whether it’s one or many of the above reasons, it doesn’t matter. Eventually, the weight of technical debt crumbles the software and you have to halt everything to do reactive maintenance.
Before we discuss what to do in reactive maintenance, let’s be clear about what NOT to do:
Do not create another hack
For the love of Sir Tim Berners-Lee, please do not create another mess to hide the existing one. Take the time to do it right.
Do not point fingers
If you have never written a bad code, you probably do not code enough or are terrifyingly oblivious about code quality.
Do not be afraid of a large refactoring
If things break, they can be fixed. It’s easier to make fixes in the clean code that you understand.
So what should you do?
1. Do an RCA
Why did your code break? What is the root cause of the problem? How can you avoid similar issues in the future?
2. Review your design again
Ask someone with a fresh pair of eyes to review your decisions. Discuss it with your team. Remember: you don’t have to do what everyone suggests. But it’s important to listen and put your personal bias aside while reviewing something.
3. Create task groups
List down everything that you can potentially do. Group them together by function like database related, auth related, library updates, folder restructuring, and file renaming, etc.
4. Separate the necessary ones from the nice-to-haves
Not everything needs to be done today. Not everything is really necessary. Don’t get carried away while making the list. Prioritize your list.
5. Fortify your tooling and guardrails.
Remove friction points. Adding reusable scripts, setting up linting, tests, automated pipelines, etc. will help you do other tasks more efficiently.
6. Set up a QA process
The new code should be reviewed by multiple people. The new system should be fully tested by multiple people. This gives you confidence. QAs are not your enemy, they are your first line of defence.
Other articles in the series
I’m glad you read the entire thing 🤓
Do you agree with my thoughts? Do you have something you would like to share? I would love to read your thoughts and experiences.
Please leave a response below.
I ❤️ software development & enjoy writing articles about it. But they do take a lot of time & effort. If you have enjoyed this article please share & recommend it.
Happy coding!