You Are Stuck in an Ugly Code Base: How to Help Yourself and Your Teammates
Learn how to write self-documenting code and make architectural improvements to improve code quality and manageability.
As a management consultant with a PhD in software engineering, I understand the challenges that come with working in a code base that is difficult to understand, debug, and maintain. This situation can be especially frustrating for developers who are trying to make improvements to the code but are unable to do so because of the complexity and lack of organization in the code base. However, there are steps that developers can take to help themselves and their teammates in these situations.
One of the most important steps is to write new code that is self-documenting, short, and concise. This means that the code should be written in such a way that it is easy to understand, even for someone who is not familiar with the code base. This is crucial because you never know who the next developer will be and what their level of expertise will be. As Robert C. Martin, author of “Clean Code: A Handbook of Agile Software Craftsmanship,” writes,
“Always write code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live.”
Writing clear and concise code ensures that the next developer can understand the code and make improvements without causing problems.
💡 Note: This is where an open-source toolchain like Bit can help. With Bit, you can isolate components within your codebase and define them as independent entities that can be developed separately, then versioned, documented, tested, and shared via Bit’s central registry. Bit lets you reuse and share components across your team and other projects. Learn more here and here.
Another step that developers can take is to follow the Boy Scout rule. This rule, which was popularized by Robert C. Martin, states that you should leave the code base in a better state than when you found it. This means that each time you visit the code base, you should make small improvements to the code. These improvements could include fixing bugs, refactoring code to make it more readable, and improving documentation. As Martin writes,
“Always check in your code a little cleaner than when you checked it out.”
By following the Boy Scout rule, developers can help to improve the code base over time, making it easier to work with.
Finally, developers can also make architectural improvements to the code base. This involves getting small measurements of the architecture and finding the areas where most changes occur. Once these areas have been identified, developers can invest in improving the architecture. This could involve decoupling different parts of the code base using abstract factory patterns or introducing interfaces for testing purposes. For example, as Anjaneyulu Batta writes in his article, “Understanding the Abstract Method Design Patterns,” using abstract methods can help to create a cleaner and more flexible architecture that is easier to maintain.
If the team does not record technical debt items, then it is important to start this task. Technical debt relates to the extra effort the developers should do, because of low-quality, shortcuts introduced to deliver faster, it is all the tasks that are invisible for the end users, but takes up time for the developers. It is important to record the root cause, and also to record technical debt items at the minute when the debt is introduced (an example could be the use of an older 3rd party component, as an update would require a larger re-write of other parts of the code).
In conclusion, developers who are stuck in an ugly code base can help themselves and their teammates by writing new code that is self-documenting, short, and concise, following the Boy Scout rule, and making architectural improvements. By doing so, developers can make the code base more manageable and improve the overall quality of the application.
References:
- Robert C. Martin, “Clean Code: A Handbook of Agile Software Craftsmanship” (blog.cleancoder.com)
- Huy Trong Nguyen, “Lessons Learnt from the Clean Code Robert C. Martin” (medium.com)
- Anjaneyulu Batta, “Understanding the Abstract Method Design Patterns” (medium.com)
Build Apps with reusable components, just like Lego
Bit’s open-source tool help 250,000+ devs to build apps with components.
Turn any UI, feature, or page into a reusable component — and share it across your applications. It’s easier to collaborate and build faster.
Split apps into components to make app development easier, and enjoy the best experience for the workflows you want:
