Clean Code

Three checks to run on any piece of code: naming, complexity, comments. Each has a concrete bar, not a vibe.

1. Naming

Every module, file, function, class, and variable name must reveal intention on its own — no need to read the body to know what it does.

Operational checks, in order:

1. Intention-revealing: name says what it does/holds, not how (elapsedTimeInDays, not d). If you need a comment to explain a name, the name failed.
2. No confusion: don't use names that differ in ways that are hard to spot (userList vs usersList), and don't call something a list unless it's actually a List type. Don't use two names for the same concept, or one name for two concepts.
3. Reduce noise: strip noise words that add no meaning — data, info, manager, object, Impl. ProductInfo vs Product — if both exist, the names are indistinguishable in practice. Prefer the shorter one and let context (folder, type) carry the rest.
4. Avoid acronyms/abbreviations: calculateInvoiceTotal, not calcInvTot. Exception: acronyms that are more standard than the spelled-out form in the domain (id, url, html) — but pick one casing convention and stay consistent.
5. Searchable: no magic numbers/single-letter names for anything beyond a tight loop index. MAX_RETRY_COUNT, not 5 or n. A name you can grep for beats one you can't.
6. Part of speech: classes/types get noun phrases (Invoice, PaymentProcessor); functions/methods get verb phrases (calculateTotal, isValid, hasExpired). A function named like a noun is a smell — it's probably returning something it should be named after, or doing too much.
7. One word per concept: pick one verb for one action across the whole codebase — don't mix fetch/retrieve/get for the same kind of operation, or add/insert/append for the same kind of mutation. Check for existing convention in the codebase before introducing a new synonym.

2. Cyclomatic complexity