clean-code

Apply the Extract Till You Drop technique: pull each identifiable step into a named function, use guard clauses for error cases at the top, and follow the Step-Down Rule so code reads from high-level to low-level. Functions should ideally be 4-10 lines doing one thing.

Names should reveal intent, answering why the thing exists, what it does, and how it is used. Use nouns for classes, verbs for methods, predicate phrasing like isActive for booleans, and make name length proportional to scope size.

Use exceptions rather than return codes, because return codes force callers to check immediately and clutter the happy path. Provide context in every exception, avoid returning or passing null, and wrap third-party APIs with exception types defined by the caller's needs.

The highest-impact smells are duplication, functions with too many or flag arguments, feature envy, magic numbers, dead code, and mixed abstraction levels. Each smell maps to a targeted refactoring such as extracting shared logic or moving methods to the class owning the data.

Write comments only to explain why, never what; the code itself should express the what through clear naming. Acceptable comments include legal headers, intent explanations, warnings of consequences, and ticketed TODOs, while redundant, misleading, and commented-out code should be deleted.

Clean tests follow the F.I.R.S.T. principles: Fast, Independent, Repeatable, Self-validating, and Timely. Each test covers one concept using Arrange-Act-Assert structure, descriptive names like shouldRejectExpiredToken, and builder helpers that read like a domain-specific language.