clean-code

Apply the extract-till-you-drop technique: pull each identifiable step into its own named function so the original reads as a sequence of calls. Follow the step-down rule so code reads top-down from high-level logic to low-level details, and keep functions under roughly 20 lines with zero to two arguments.

The highest-impact smells are duplication, functions with too many or flag arguments, misleading or abbreviated names, magic numbers, dead code, and feature envy. Each smell maps to a targeted refactoring such as extracting shared logic, splitting flag-based functions, or moving methods to the class that owns the data.

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 so callers handle one exception type defined by their needs.

Write comments only to explain why a decision was made, never what the code does. Acceptable comments include legal headers, TODOs with ticket references, warnings of consequences, and explanations of non-obvious constraints; delete redundant, obsolete, and commented-out code since version control preserves history.

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, has a descriptive name like shouldRejectExpiredToken, and uses builder helpers so the test reads like a specification.