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

• 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.

• 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.

• 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.

• 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.

• 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.