Code Quality Expert

clean code

When reviewing or writing code, apply these guidelines:

Clean Code Guidelines

Constants Over Magic Numbers

• Replace hard-coded values with named constants
• Use descriptive constant names that explain the value's purpose
• Keep constants at the top of the file or in a dedicated constants file

Meaningful Names

• Variables, functions, and classes should reveal their purpose
• Names should explain why something exists and how it's used
• Avoid abbreviations unless they're universally understood

Smart Comments

• Don't comment on what the code does - make the code self-documenting
• Use comments to explain why something is done a certain way
• Document APIs, complex algorithms, and non-obvious side effects

Single Responsibility

• Each function should do exactly one thing
• Functions should be small and focused
• If a function needs a comment to explain what it does, it should be split

DRY (Don't Repeat Yourself)

• Extract repeated code into reusable functions
• Share common logic through proper abstraction
• Maintain single sources of truth

Clean Structure

• Keep related code together
• Organize code in a logical hierarchy
• Use consistent file and folder naming conventions

Encapsulation

• Hide implementation details
• Expose clear interfaces
• Move nested conditionals into well-named functions

Code Quality Maintenance

• Refactor continuously
• Fix technical debt early
• Leave code cleaner than you found it

Testing

• Write tests before fixing bugs
• Keep tests readable and maintainable
• Test edge cases and error conditions

Version Control

• Write clear commit messages
• Make small, focused commits
• Use meaningful branch names

code quality and best practices

When reviewing or writing code, apply these guidelines:

• Adhere to code quality and best practices.
• Apply relevant paradigms and principles.
• Use semantic naming and abstractions.

code quality standards

When reviewing or writing code, apply the principles above consistently. Focus on:

• Readability over cleverness
• Consistency within the codebase
• Progressive improvement (leave code better than you found it)

Consolidated Skills

This expert skill consolidates 1 individual skills:

• code-quality-expert

Iron Laws

1. ALWAYS leave code cleaner than you found it — every change is an opportunity for progressive improvement; accumulating small improvements prevents large-scale refactors from becoming necessary.
2. NEVER use magic numbers — hard-coded values without context make code unreadable and unmaintainable; always extract to named constants with descriptive names that explain the purpose.
3. ALWAYS write self-documenting code first, then add comments only for "why" — comments explaining "what" the code does are redundant and become stale; reserve comments for non-obvious design decisions.
4. NEVER allow functions to do more than one thing — single responsibility is the strongest predictor of testability and maintainability; a function needing a "and" in its name should be split.
5. NEVER optimize prematurely — write clear, correct code first; profile to identify actual bottlenecks before optimizing; premature optimization produces complex code with unmeasured benefit.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Magic numbers in logic	if (status === 200) is opaque; value could change	Extract to const HTTP_OK = 200 with clear name
Comments explaining "what" not "why"	Code changes make comments stale and misleading	Write self-documenting code; comment only design rationale
God functions (>50 lines, multiple concerns)	Hard to test, debug, and modify independently	Extract single-purpose functions with clear names
Premature optimization	Adds complexity before proving a bottleneck exists	Profile first; only optimize measured hot paths
Duplicated code blocks	Bug fixes must be applied in N places	Extract to reusable function; DRY principle

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing: Record any new patterns or exceptions discovered.

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.