The standard of good codebases
As software engineers, it’s no surprise that we often find ourselves in a conversation talking about working on a bad codebase or seldomly a good one. But what makes a good codebase exactly? I will summarise my opinion here and please comment below if you have different thoughts.
Serve its purpose
First and foremost, a good codebase should function well for its purpose. It should be secure and run reliably and efficiently enough to fulfil the requirements.
Decent overall design
Secondly, the codebase should adopt a proper design pattern and be properly modularised. This is especially important for a sizeable codebase because navigating in a large codebase that has no patterns would be like walking in a maze with the exception that, this time, there is no fun but nightmares. Reasonable module separation, clear folder/file structure and all the principles(clean code, SOLID etc.) that we learned would help to some extent. Some principles that are critical to a good codebase will be listed separately below as well.
Consistency
Being consistent in code style(naming conventions and code formatting styles etc.) will help new joiners read and understand code with comfort, which usually can be achieved by employing some linting tools.
Consistency in logic and having consistent behaviours across the codebase will make reasoning and debugging process easier and reduce confusions.
Lastly, consistently using one pattern in one codebase is also a good indicator of a good codebase. For example, mixing VIPER and MVVM patterns in one codebase will confuse developers when they start working on a new feature.
KISS(keep it simple, stupid)
The good codebase is written in a way that’s simple and intuitive to read. This is especially true for codebases that are supposed to be maintained in a long term where team members changes are inevitable. Concise, clear code is friendly to new developers and makes them easy to understand and add new functionalities to it.
DRY(Don’t Repeat Yourself)
Code duplication should be avoided in any good codebases. We have a dedicated article for this topic here.
Duplication can also break consistency because it’s easy to forget updating all the duplicated code pieces when there’s a need for a change to them. Forgetting any one of these would bring bugs into systems and breaks the consistency.
Error/Exception Handling
Errors and exceptions are an integral part of the code and a good codebase handles them carefully. It’s normal that we need more effort to take care of these unhappy paths sometimes.
Logger
Log records the runtime behaviour of the system, which can be very helpful to debug unexpected issues. A good codebase should configure logging tools and ideally tracks different levels of events.
Test coverage
Unit testing(and UI testing for some user facing systems) is a great way to ensure code correctness. Ideally it covers all the major business logics in the system. It’s worth mentioning that unit testing also plays a crucial role in refactoring processes because it will help guard that the new code implementation l performs the same logic as before.
Documented/Commented Properly
Better design documentation and comments in code help the new developer in the team understand code quicker. On this regard, Documentation as Code (Docs as Code) is a great practice, which treats documentation as code and keeps documentation updated along with the code changes.
Continuously evolving
Lastly, a good codebase should keep evolving, adopt new technologies when time is proper. The new technologies should be carefully designed and verified before fully refactoring the code to adopt them and the transition process should be handled with care.
Sharing is caring!