Writing Clean Code

Code is verified by compilers and tests; prose is verified by nobody. So edits update the code and skip the comment, and the comment quietly becomes false. Fixes: fewer comments, put facts in code/tests/types, and review comments as code.

Throw for unexpected failures the caller usually can't handle locally — bugs, infrastructure outages. Return a Result/Either when failure is an expected outcome the caller must decide about, because it puts the failure in the type signature and can't be forgotten.

Small files are easier to understand than large ones. A file that keeps growing usually means it has taken on several responsibilities, so the fix is splitting it up — not adding more comments, headers, or blank lines.

A hidden side effect is a change the function makes that its name doesn't advertise — mutating a global, a parameter, or session state inside something that looks like a check. It breaks callers' assumptions and creates order dependencies between calls that nothing enforces.

If you cannot name something without "And" or a vague word like "Manager", it probably does more than one job — the naming problem is really a design problem. Renaming is free inside a function, but a name in a public API, database column, event field, or metric is a contract others depend on.

The further a name travels from its declaration, the more descriptive it must be. i is fine in a three-line loop; a module-level export needs a full phrase. Searchable means findable by text search — MAX_RETRIES can be found, 3 cannot. Pronounceable means you can say it aloud.

A boundary pays off when the thing behind it is likely to change, is hard to test, or would otherwise spread everywhere. It stops paying when the abstraction just mirrors the dependency, when the dependency is a stable standard, or when its behaviour leaks through anyway.

Do not fail the build on existing code. Freeze current violations as a baseline and enforce the threshold only on new and changed code, so the codebase improves as it is touched instead of demanding a big-bang cleanup.

Give each kind of knowledge one home: code and tests for behaviour, comments for local why and hazards, commit history for change history, issue tracker for planned work, ADRs for decisions, generated reference for public APIs. Require TODOs to link an issue and expire them.

Agree one error taxonomy (client error / business rejection / transient infrastructure / bug), give each a stable code and a retryable flag, translate to transport in one place per service, log once with a correlation id, and make retries safe by requiring idempotency.

The team standard wins. Code should look like one person wrote it, so personal preference gives way to the committed convention; if you disagree, propose a change to the standard rather than formatting your own files differently.

Stop when a helper isn't a nameable concept — when its name just paraphrases the caller, it has one caller, or it needs many parameters to rebuild the caller's context. Set a policy on naming, cohesion, and abstraction level in review; use line-count linting only as a smell trigger, never as a gate.