clean-code_skill

Overview

This skill detects violations of Clean Code principles and suggests practical refactorings to improve readability, maintainability, and design. It focuses on naming, function structure, error handling, class design, and common code smells. Use it to guide incremental improvements and prepare code for larger refactors.

How this skill works

The skill scans code patterns and flags signals such as single-letter names, long methods, many parameters, null returns, and mixed responsibilities. For each finding it proposes targeted refactorings—rename suggestions, method extraction, parameter objects, value objects, or class splits—along with a short rationale. It also recommends low-risk, opportunistic changes you can apply immediately following the Boy Scout Rule.

When to use it

• During code reviews to surface maintainability issues quickly
• Before or during refactoring to prioritize concrete changes
• When onboarding to understand problematic areas in unfamiliar code
• To enforce consistent naming and small-function practices
• When preparing legacy code for new features or tests

Best practices

• Prefer intention-revealing names and avoid abbreviations or temp/data suffixes
• Keep functions small and at one level of abstraction; extract helpers liberally
• Limit function arguments (prefer parameter objects or builders for >3 params)
• Make error handling explicit: use exceptions or Optionals instead of null/error codes
• Split classes by responsibility and extract cohesive collaborators
• Apply one small improvement per edit (Boy Scout Rule) to reduce review risk

Example use cases

• Detect and rename cryptic variables and suggest clearer identifiers
• Identify a 50-line method and propose extracted helper methods with clear responsibilities
• Find repeated parameter groups and recommend creating a parameter object
• Replace null-return sites with Optional or empty-collection alternatives
• Flag classes with mixed concerns and outline a split into focused classes