clean-code

Score the code 0-10 against six disciplines: meaningful names, small single-purpose functions, minimal comments, exception-based error handling, clean tests, and smell detection. Then list the specific gaps between the current score and 10/10 with targeted refactorings.

Apply the extract-till-you-drop technique: pull each identifiable step into a named function so the original reads as a top-down narrative. Replace flag arguments with separate functions, use guard clauses for early returns, and introduce parameter objects when argument counts exceed two.

Common smells include duplication, long parameter lists, feature envy, dead code, magic numbers, and shotgun surgery. Each maps to a targeted refactoring: extract shared logic, introduce parameter objects, move methods to the data's class, delete dead code, and name constants.

Use exceptions rather than return codes so the happy path stays separate from error handling. Provide context in every exception message, never return or pass null, and apply the Special Case pattern such as empty collections or Optional instead of null returns.

Write comments only to explain why, never what; a comment explaining what code does signals the name or structure should improve instead. Legal headers, TODOs, and public API documentation are acceptable, while commented-out code and changelog comments should be deleted.

The principles are heuristics, not absolute rules, and mechanical application can over-fragment simple code. Premature refactoring without tests risks regressions, so write characterization tests first and refactor in small verified steps rather than alongside feature work.