Dear new developer,
I’ve spent a lot of my time maintaining working code. I think that is more typical of software developers than working in greenfield development. Yes, there are definitely jobs where you are writing more new code than maintaining, upgrading, bug fixing and improving old code (startups without product market fit being one, consulting being another) but in general code is expensive and folks want to run it for a long time.
Often you’ll jump into code to fix a bug, investigate an issue or answer a question.
When you do so, improve it. This doesn’t mean you rewrite it, or upgrade all the libraries it depends on, or rename all the variables.
You don’t need to transform it.
But you should make it better. Just clean it up a bit. Doing so makes everyone’s lives just a bit better, helps the codebase in a sustainable way, and assists the business by making its supporting infrastructure more flexible.
What are some ways to improve the code when you are in it?
Document
Whether that is a comment that explains something tricky, a larger piece of documentation external to the code which explains how to interact with it, or fixing a typo, trustworthy documentation is key to interacting with code. This is a good way to start improving a codebase because it has minimal impact on the actual code. Therefore it is low risk. But if you’ve ever had a great comment explain a confusing bit of code, you’ll appreciate the time this effort can save.
You can also help documentation by removing old, crufty docs. If you see a comment that doesn’t apply, remove it. If there’s cut and paste documentation which doesn’t apply, get rid of it. That cleans up the code for the next person to come along (who might be you.
Write a test or improve a test
Tests help you write maintainable, extensible code that others can change fearlessly. If you run across code that isn’t tested and you have time and the supporting framework to write one, do so.
Even if it tests simple functionality such as “can I instantiate this object” or “how does this function react when I pass it two null values”, an additional test will help the robustness of the code.
Refactor it
This is one of the most flexible improvements. Refactoring code can range from renaming a variable to be more true to its nature to an overhaul of an entire module. Start small and don’t get wrapped up in perfection. Make the code clearer in intent.
It’s easy with refactoring to get wound around an axle and make too many changes and end up with broken things. Timeboxing is one technique I use to avoid, or at least minimize, my tendencies toward this when refactoring. If all I have is 30 minutes, I’ll make my changes smaller in scope.
Upgrade a dependency
It’s sometimes a winding path, but upgrading your dependencies regularly is a good way to maintain the code. I remember working in a fork of struts. It was an important application for the company, but we didn’t spend the time upgrading the dependencies, because it was too painful. Eventually, parts of the code became harder to update. The entire application couldn’t benefit from newer technologies and paradigms because of the older dependencies holding it back.
It never feels good to spend time updating a dependency; to me this always feels like running in place. But if you don’t do so, eventually dependencies will end of life and you’ll be forced to update. That’ll be even less pleasant.
All of these actions not only help others because they improve the quality of the code, they also provide examples to other developers on how to do so. For example, it is far easier to write the second test in a suite than the first. You can cut and paste a lot of the setup code and tweak only what is different. The first bit of documentation will inspire more.
Code isn’t everything, but it is an important work output. Whenever you touch it, you should strive to leave it in a better place that it was before you did so.
Sincerely,
Dan
Top comments (0)