clean-code

Apply the Extract Till You Drop technique: pull each identifiable step into its own named function, use guard clauses for error cases, and follow the Step-Down Rule so code reads top-down from high-level to low-level abstraction. Aim for functions of 4-10 lines doing one thing.

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 specific refactoring such as extracting shared logic, splitting functions, or renaming for intent.

Use exceptions rather than return codes, because return codes force callers to check immediately and clutter the happy path. Provide context in every exception, prefer unchecked exceptions in application code, and never return or pass null.

Comments are acceptable for legal headers, explaining why a decision was made, warnings of consequences, and tracked TODOs. Comments explaining what code does signal the code itself needs clearer naming or extraction, and commented-out code should always 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, has a descriptive name like shouldRejectExpiredToken, and uses builder helpers for readable setup.