A Maintainable Codebase Starts with an Opinionated Codebase

I have worked with a ton of kinds of codebases throughout my career so far. Some of them are pleasant to work with, and most of them are the opposite. But it’s always bugging me on why are some of them are really wonderful to work with and some of them are not?

The Phases

Every single interaction that you will have with some form of codebase will fall into one of these categories:

• Early encounter: The project is just getting started. The characteristic is that you’ve had a chance to make some quite big refactor in the codebase without too much hassle and burden in your mind;
• Mid-journey encounter: If you join a new company, and the company already has a system in place, this is most likely (even though not always) is the phase where you’ll interact with the codebase. The codebase will have its own complexity and doing some refactoring will require some serious considerations.
• Legacy encounter: Well, this is (most likely) where you’ll end up whenever you join a large (or old) companies. The systems are there (maybe mature, or maybe not). Not even a refactoring, doing a little change requires a lot of planning and the right execution.

The Reality

Every single one of us are hoping that whatever phase that we encounter on a codebase, it would be pleasant to work with. We hope that the codebase is well-structured, well documented, well tested, and well performed (assumed deployed properly).

But as the reality kicks in, each stage has its own problem.

An early codebase might be well-structured and performed since the number of features and integrations are quite small, but often time it’s not well documented and tested.

A little-bit more mature codebase (Mid-journey encounter) is often time lacks all of them 🤣. The features and integrations are growing, but mid-size team will often times are ruling out the tests, documentations, and the performances.

A mature codebase is often already well documented and tested. But since a ton of hands are got in touch with the codebase, a mature codebase is often difficult to work with since the consistent structure are not there anymore. AND, the documentation provided is not helpful at all (it’s there, but it doesn’t help).

Then, How To?

Among all of those three phases above, the Mid-journey encounter is critical. This is the phases where the habits, structure, conventions are formed. This phase’s development should be opinionated. Opinions are formed by all the team members, discussed, agreed upon, and followed by everyone.

Every changes that would be made to the codebase should be created based off of the agreed upon opinions and strictly reviewed based off of the agreed upon opinions.

Why Not in the Beginning?

In the early life of a codebase, there are few cases:

• If it was developed by a single or small team of developers, it’s better to just get things done. If the developers are experienced enough, they will likely put the codebase off for a good start.
• If it was developed by quite a lot of developers, it’s the phase where they should go to “war”. Throw all of their personal preferences, opinions, and tastes into the codebase, discuss it, and agreed upon a path for the codebase’s opinions and formed that the future developers can consistently follow.