Six Rules That Keep a Codebase Worth Working In

Rules you have heard and probably misapplied

Every one of these gets quoted as an acronym in code review, usually by someone who read the expansion and not the reasoning. Applied without judgement they produce code that is worse than if nobody had heard of them.

So here is each one with the thing it is actually protecting against, and the way it goes wrong when taken too far.

Separate concerns

Break a large problem into pieces, and give each piece one job.

The test is whether you can describe what a function or a module does without using the word "and". If the description is "it validates the input and saves it and sends the confirmation email", that is three things, and the day you need to save without emailing you will find out why that matters.

Where it goes wrong: splitting for the sake of splitting. Six files with one function each, calling each other in a chain, is not separation of concerns, it is the same logic with more places to look. Split when a piece has a reason to change on its own.

Do not repeat yourself

The same logic in three places will get fixed in two of them.

That is the whole argument, and it is a good one. Duplicated knowledge drifts, and drift is where bugs live.

Where it goes wrong: and this one goes wrong constantly. DRY is about knowledge, not about characters. Two functions that happen to look similar today but exist for unrelated reasons are not duplication. Merging them creates a single function with a boolean parameter that does two different jobs badly, and the next requirement adds a second boolean.

Duplication is cheaper than the wrong abstraction. If you are not sure whether two things are the same thing, wait. The third occurrence usually tells you.

Keep it simple

Between two solutions that work, take the one that is easier to read.

Clever code is a debt taken out against your future self at three in the morning. Nobody has ever opened a file at three in the morning and been pleased to find something clever.

The practical version: write it the obvious way first. Only make it less obvious when you have a measurement that says you need to, and leave a comment explaining what the measurement was.

Where it goes wrong: simple is not the same as short. A dense one liner with three chained operations is short and it is not simple. Simple means the reader can predict what it does without running it.

You are not going to need it

Build what is required now. Not what you think might be required later.

Speculative flexibility is the most expensive habit in software. The configuration option nobody sets, the plugin system with one plugin, the abstraction layer over the one database you will ever use. Every one of those has to be maintained, understood by every new joiner, and worked around when the actual requirement arrives and does not fit the shape you guessed.

Where it goes wrong: it is not an excuse to ignore things you know are coming. If three customers have asked for a second currency, that is a requirement with a slow arrival, not speculation. The rule is about imagined futures, not scheduled ones.

Let tests shape the design

Write the test first, watch it fail, write the smallest code that makes it pass, then clean up.

The failing step is not ceremony. A test you never saw fail might be passing for a reason unrelated to your code, and you will not find out until it matters.

The part people miss is that this is a design technique before it is a verification technique. Code that is hard to test is usually badly structured, and writing the test first is how you find that out in ten minutes rather than after a week of building.

Where it goes wrong: treating it as all or nothing. Very few people write every line this way. Use it where the behaviour is well defined and the logic is worth getting right, which in most codebases is a minority of the code and the most important minority.

Write for the person who arrives later

That person is usually you, six months on, with no memory of any of this.

The rule for comments: the code says what, the comment says why. A comment restating the line above it is noise that will eventually contradict the code. A comment explaining why the timeout is 4,500 milliseconds, or why you are deliberately not using the obvious library here, is the most valuable thing in the file.

The same applies outward. A pull request description saying what changed is redundant, because the diff says that. One saying why this approach and what else was considered is what makes review useful.

The one that matters most

Leave the code better than you found it.

Not a rewrite. You are in a file for an unrelated reason, you notice a badly named variable, you rename it. A function has grown to two hundred lines and you pull out the obvious piece. Small, in passing, unremarkable.

Codebases do not usually rot through one bad decision. They rot through ten thousand small deteriorations that everybody noticed and nobody had time for. The habit of fixing the small thing in front of you, right then, is what stops that.

It is also the least visible good habit in engineering, which is worth knowing so you do not expect credit for it.

The rule behind the rules

All six are the same instruction in different clothing: optimise for reading, not for writing.

Code is read far more often than it is written, mostly by people without the context you have now, frequently under time pressure. Every one of these rules trades a little convenience while writing for a lot of clarity while reading.

When two of them conflict, and they will, that is the question to fall back on. Which version will the next person understand faster.