coding-rules

shinpr's avatarfrom shinpr

Applies coding standards for clean, maintainable code. Use when: writing functions, handling errors, refactoring, or reviewing code style.

⭐30stars🔀3forks📁View on GitHub🕐Updated Dec 31, 2025

When & Why to Use This Skill

This Claude skill serves as an automated guardian for code quality and maintainability. It enforces rigorous software engineering standards, including aggressive refactoring, the YAGNI (You Ain't Gonna Need It) principle, and structured error handling. By providing a comprehensive framework for function design, dependency injection, and clean documentation, it helps developers eliminate technical debt, improve readability, and ensure long-term project scalability across various programming environments.

Use Cases

  • Automated Code Audits: Use the skill to review pull requests or existing files to identify 'code smells,' unused logic, and violations of clean code principles.
  • Refactoring Legacy Code: Systematically simplify complex conditional branches and large functions into modular, testable components while maintaining behavioral integrity.
  • Standardizing Error Handling: Implementing consistent, layer-specific error propagation and structured logging strategies to improve system observability and security.
  • Architectural Guidance: Applying dependency injection and parameter management rules to ensure code is decoupled, modular, and easy to unit test.
  • Documentation & Style Alignment: Enforcing concise, 'why-focused' commenting rules and naming conventions to ensure the codebase remains self-documenting.
namecoding-rules
description"Applies coding standards for clean, maintainable code. Use when: writing functions, handling errors, refactoring, or reviewing code style."

Development Rules

Language-Specific References

For language-specific rules, also read:

Basic Principles

✅ Aggressive Refactoring

  • Continuously improve code structure and readability
  • Make code changes in small, safe steps
  • Prioritize maintainability over initial implementation speed

❌ Unused "Just in Case" Code - YAGNI principle

  • Don't write code for hypothetical future requirements
  • Delete unused functions, variables, and imports immediately
  • Keep codebase lean and focused on current needs

Comment Writing Rules

  • Function Description Focus: Describe what the code "does", not how it works
  • No Historical Information: Do not record development history in comments
  • Timeless: Write only content that remains valid whenever read
  • Conciseness: Keep explanations to necessary minimum
  • Explain "Why": Comments should explain reasoning, not implementation details

Function Design

Parameter Management

  • 0-2 parameters maximum: Use structured data (object/struct/dict) for 3+ parameters
    ✅ Good: createUser({name, email, role})
    ❌ Avoid: createUser(name, email, role, department, startDate)
    
    Note: Use your language's idiomatic approach for grouping parameters

Dependency Injection

  • Inject external dependencies explicitly: Ensure testability and modularity
  • Pass dependencies as parameters (functions, constructors, or other language-appropriate mechanisms)
  • Avoid global state, direct instantiation, or implicit dependencies
  • Prefer interfaces/contracts over concrete implementations where applicable

Error Handling

Absolute Rule: Error suppression prohibited. All errors must have log output and appropriate handling.

Layer-Specific Error Handling

  • Presentation Layer: Convert errors to user-friendly messages, log excluding sensitive information
  • Business Layer: Detect business rule violations, propagate domain-specific errors
  • Data Layer: Convert technical errors to domain errors

Structured Logging and Sensitive Information Protection Never include sensitive information in logs:

  • Passwords, tokens, API keys, secrets
  • Credit card numbers, personal identification numbers
  • Any personally identifiable information (PII)

Asynchronous Error Handling

  • Use appropriate error handling mechanisms for your language
  • Always log and appropriately propagate errors
  • Set up global error handlers where applicable

Clean Code Principles

✅ Recommended Practices

  • Delete unused code immediately
  • Remove debug statements and temporary logging
  • Use meaningful variable and function names
  • Keep functions small and focused on single responsibility

❌ Avoid These Practices

  • Commented-out code (use version control for history)
  • Magic numbers without explanation
  • Deep nesting (prefer early returns)
  • Functions that do multiple unrelated things

Refactoring Techniques

Basic Policy

  • Small Steps: Maintain always-working state through gradual improvements
  • Safe Changes: Minimize the scope of changes at once
  • Behavior Guarantee: Ensure existing behavior remains unchanged while proceeding

Implementation Procedure

  1. Understand Current State
  2. Make Gradual Changes
  3. Verify Behavior
  4. Final Validation

Priority Order

  1. Duplicate Code Removal
  2. Large Function Division
  3. Complex Conditional Branch Simplification
  4. Architecture Improvement

Performance Considerations

General Principles

  • Measure before optimizing (avoid premature optimization)
  • Focus on algorithmic complexity over micro-optimizations
  • Consider memory usage, especially with large datasets
  • Use appropriate data structures for the use case

Resource Management

  • Properly close files, connections, and other resources
  • Be mindful of memory leaks in long-running applications
  • Use efficient algorithms for data processing

Code Organization

File Structure

  • Group related functionality together
  • Separate concerns (business logic, data access, presentation)
  • Use consistent naming conventions throughout the project
  • Keep configuration separate from business logic

Modularity

  • Write small, focused modules/functions
  • Minimize dependencies between modules
  • Use clear interfaces between components
  • Follow single responsibility principle