I recently finished up a project where I and a coworker worked to help maintain a large codebase. We not only were tasked with fixing bugs, adding new features, and cleaning up confusing code. We also had to ensure that the team we worked with would be able to do effective work after we left the project. Here are some things we did to help them as our time on the project came to an end.
1. Explain your decisions.
When I first joined the project, there were many parts of the codebase that were confusing and hard to work with. This meant that when the project’s current team took over, they were unsure how many parts of the code worked. This resulted in the current developers adding new code, which was sometimes unnecessary — adding to the cycle of confusion.
While cleaning up much of the old code and adding new code, we made sure to try to explain our decisions to the team. We also worked to make our code more self-documenting, and we added comments when necessary. In the future, when the team needs to make changes to these parts of the code, they will know which parts do what and where they need to make changes.
2. Leave the codebase with better practices.
It can be difficult to follow good developing practices when the codebase is already messy. Part of what we needed to do was introduce better practices to the project. We introduced ESlint into the project to help clean up inconsistencies. This helps ensure that consistent patterns are being used in the future. We also worked to add unit tests to improve test coverage.
Of course, when these practices get introduced to a project, it’s important to explain why they are important. Show how clean, self-documenting code makes development easier. If the team doesn’t see the benefit in tools like ESLint or writing unit tests, they may stop using them in the future.
3. Show them which future improvements could be made.
Unfortunately, didn’t have time to fix every issue we wanted to. At the end, I wrote up a small document for the team with future ideas for improvement. It described parts of the codebase that could cause issues and gave advice on how to fix them.
For example, the main part of the codebase was a large class that was several thousand lines long. When someone needed to make changes to a part of the codebase, there was a good chance that it needed to made there. Since the class was so large, it could sometimes be difficult to determine where to make those changes.
In the ideas document, I explained that the class was taking on more responsibility than it needed to. I pointed out several functions within the class that could be pulled out and made into their own classes. And I explained how doing this would make it easier and faster to make changes in the future.
It’s essential to leave the client with the tools and knowledge they need to maintain the quality of the software you write. Communication and openness are a must.
Source: Atomic Object