How to Build a Compounding Codebase

by Timo Moilanen

Many software products and frameworks we use daily were created by small teams. Why do some teams achieve more than others? How can engineers stay happy and productive as the project matures? The answer is to build a compounding codebase, and this post explains what you need to do to make your code compound.

“Compound interest is the eighth wonder of the world. He who understands it, earns it … he who doesn’t … pays it.”

― Albert Einstein

The definition of a compounding codebase is that development should become easier, not harder, as your project matures. How does this happen? The short answer is through constant iteration and obsessing over clarity. In practice, it boils down to these principles:

What great software looks like

Data structures should align with the problem you are solving

• Poorly aligned data structures make every feature unnecessarily complex and your codebase unreadable.
• If you get the “it shouldn’t be this hard” frustration, you are probably right. Take a step back and revisit your data structures.
• A relational database is not an object. Do not try to mimic it as such.

Naming things is your most important documentation

• Use consistent vocabulary from the domain language. Overloaded terms confuse people.
• Replace generic verbs (like get) with specific ones. In our codebase, we load from database, read from file, fetch over http, pick from collection, compute from given input, and transform objects toSomething.
• If a function has side effects, it should be clearly stated in its name (e.g., function saveUser(…)).

Reduce the next developer’s cognitive load

• Orthogonality: One function should do one thing. If you can’t easily name your function, you have probably done something wrong.
• Document rationale: Good code is self-explanatory about what it does. Comments should explain why you chose to do it that way.
• Fail loudly: If your function assumes that an input number is positive, it should throw an error if it isn’t. Silent bugs are the worst.

The process of building great software