clean-code_skill

Overview

This skill applies the core principles from Robert C. Martin's Clean Code to help you write, review, and refactor code for greater readability, maintainability, and correctness. It focuses on naming, small functions and classes, comments, error handling, and unit testing to turn "code that works" into code other developers can confidently change.

How this skill works

The skill inspects code and recommends concrete changes: better names, smaller functions and classes, removal or replacement of misleading comments, clearer control flow, safer error handling, and appropriate tests. It also provides a short checklist and targeted heuristics for common code smells (rigidity, fragility, needless complexity) and prescribes corrective patterns like single-responsibility extraction, DTOs, and Law of Demeter fixes.

When to use it

• During authoring of new features to keep code high-quality from the start.
• When reviewing pull requests to provide actionable, principle-based feedback.
• Refactoring legacy modules to identify and remove code smells.
• Improving team standards and onboarding new developers to a consistent style.
• Designing APIs, classes, or public interfaces that other teams will consume.

Best practices

• Prefer intention-revealing, searchable names for variables, functions, and classes.
• Keep functions and classes small; aim for single responsibility and one level of abstraction.
• Replace many comments with clearer code; use comments only for legal, clarifying, or intent-bearing notes.
• Use exceptions over return codes and avoid returning or passing null values.
• Write unit tests first where possible and follow F.I.R.S.T. principles for test quality.

Example use cases

• Refactor a 200-line method into small, well-named helper functions and clear control flow.
• Review a pull request and flag misleading variable names, hidden side effects, or complex conditionals.
• Convert ad-hoc data blobs into DTOs and hide implementation behind interfaces for safer evolution.
• Improve error handling by replacing error codes with typed exceptions and explicit try/catch scopes.
• Add focused unit tests to cover edge cases uncovered during refactoring and to prevent regressions.