clean-code

Clean Code: Structure, Naming and Cohesion

Most defects are not clever. They are the ordinary consequence of code that is harder to read than it needed to be. A function that does three things hides which one broke. A name that lies sends the next reader to the wrong file. A module that depends on everything cannot be changed without changing everything.

So the work is not cleverness. It is applying a small number of well-established structural disciplines consistently, and being willing to keep applying them after the code already works.

The line that does most of the work:

Code is read far more often than it is written, and almost always by someone with less context than the author had. Optimise for the reader who arrives in six months knowing nothing. If your change makes sense only because you remember why, it is not finished.

The five disciplines

Every recommendation below reduces to one of these. Naming them keeps a review from collapsing into taste.

Single responsibility. A unit should have one reason to change. When you cannot describe a function without "and", it is doing two things, and the two things will need to change on different schedules. Split along the seam where the reasons differ, not where the line count is convenient.

Cohesion over proximity. Things that change together belong together. Code grouped by technical layer (all the controllers here, all the models there) scatters a single feature across the tree, so every change touches five directories. Group by what the code is about.

Explicit dependencies. A unit should declare what it needs rather than reach for it. Constructor parameters and function arguments are declarations; module-level singletons, global config and ambient state are not. The test for this is whether the unit can be exercised without standing up its whole world.

Names that survive being read alone. A name is the only documentation that cannot go stale, because changing the code without changing the name is visible. Prefer a longer name that is accurate to a short one that is approximately right. elapsed_ms beats t.