clean-code

Clean Code Principles

Use these when you write, review, or refactor code.

Treat these as directional principles. Where a repo's established precedent or a language's own idioms conflict with a rule here, follow the local convention and match the surrounding code.

---

1. Naming & Readability

1.1 Avoid Disinformation

Never use variable names that create false expectations, contain misleading technical terms, or use visually confusing characters.

Do:

• Use names that honestly reflect the data structure (accountsMap, accountsGroup).
• Use distinct names for classes/variables so autocomplete doesn't trick you.

Don't:

• Name a map accountList just because it holds several items; to a programmer "list" means an indexed structure.
• Create names that vary in tiny ways (e.g., ABCManagerForEfficientProcessingOfUsers vs ...PersistingOfUsers).
• Use characters that look identical (lowercase l vs 1, uppercase O vs 0).
  • Bad: int a = l; if (O == l) a = O1; else l = O1;

1.2 Make Meaningful Distinctions

If two things have different names, they must do different things. Avoid meaningless noise words and number series.

Do:

• Reveal the actual role of variables (e.g., array, condition, transformation).
• Use specific, role-based names for classes (e.g., OrderValidator, OrderRepository, OrderCalculator).

Don't:

• Add meaningless noise suffixes when you can't think of a better name (e.g., OrderManager, OrderHandler, OrderController, OrderProcessor all existing side by side).

1.3 Use Searchable, Pronounceable Names

Names should read as natural words and match the size of their scope, so they can be spoken aloud and found by search. Avoid cryptic abbreviations, single letters outside tiny scopes, and raw magic numbers.

Do:

• Use real words that describe intent.
  • Good: let generationTimestamp = new Date();
• Use single letters (i, j) only in tiny scopes, like a short for loop.

Don't:

• Mash abbreviations into cryptic strings.
• Use single letters in larger scopes (searching for e returns thousands of useless hits).
• Use an abbreviation that reads fine but decodes several ways: in const tx = t[i], is tx time, tax, text, or transaction? A pronounceable, searchable name can still force the reader to keep a lookup table in their head.