开发与测试
coding-principles
Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.
shinpr · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add shinpr/claude-code-workflows --skill coding-principles技能说明
name: coding-principles description: Language-agnostic coding principles for maintainability, readability, and quality. Use when implementing features, refactoring code, or reviewing code quality.
Language-Agnostic Coding Principles
Core Philosophy
- Maintainability over Speed: Prioritize long-term code health over initial development velocity
- Simplicity First: Choose the simplest solution that meets requirements (YAGNI principle)
- Design Convergence: Deliver the current required outcome with the least new design surface. Selecting persistent state, public or cross-boundary contracts, behavioral modes, reusable abstractions, or component splits carries enough surface to justify the full convergence process first.
- Explicit over Implicit: Make intentions clear through code structure and naming
- Delete over Comment: Remove unused code instead of commenting it out
Code Quality
Continuous Improvement
- Refactor related code inside the accepted outcome and governing boundaries when it reduces the change's risk or maintenance cost
- Improve code structure incrementally
- Keep the codebase lean and focused
- Delete code proven obsolete by the requested change after checking its callers; report uncertain or out-of-scope cleanup separately
Readability
- Use meaningful, descriptive names drawn from the problem domain
- Use full words in names; abbreviations are acceptable only when widely recognized in the domain
- Use descriptive names; single-letter names are acceptable only for loop counters or well-known conventions (i, j, x, y)
- Extract magic numbers and strings into named constants
- Keep code self-documenting where possible
Function Design
Parameter Management
- Group related positional parameters into an object, struct, or dictionary when call-site clarity or coordinated evolution requires it. Retain positional parameters when their order is conventional and the call remains clear, or an external/public signature requires them
- Preserve external/public signatures unless their migration is part of the accepted outcome or governing artifact
Single Responsibility
- Each function should do one thing well
- Extract a function when independently changing responsibilities or obscured control flow make the current unit harder to understand, verify, or reuse; retain a cohesive domain flow when extraction would create artificial coupling
- Extract complex logic into separate, well-named functions
- Functions should have a single level of abstraction
Function Organization
- Pure functions when possible (no side effects)
- Separate data transformation from side effects
- Use early returns to reduce nesting
- Use early returns or extraction when nesting obscures state transitions or decision ownership; retain nested structure when it maps the domain decision more clearly
Error Handling
Error Management Principles
- Always handle errors: Log with context or propagate explicitly
- Log appropriately: Include context for debugging
- Protect sensitive data: Mask or exclude passwords, tokens, PII from logs
- Fail fast: Detect and report errors as early as possible
Error Propagation
- Use language-appropriate error handling mechanisms
- Propagate errors to appropriate handling levels
- Provide meaningful error messages
- Include error context when re-throwing
Dependency Management
Loose Coupling via Parameterized Dependencies
- Inject external dependencies as parameters (constructor injection for classes, function parameters for procedural/functional code)
- Depend on abstractions, not concrete implementations
- Minimize inter-module dependencies
- Facilitate testing through mockable dependencies
Reference Representativeness
Verifying References Before Adoption
When adopting patterns, APIs, or dependencies from existing code:
- IF a reference sample covers only nearby files → THEN confirm the pattern is representative by checking relevant repository usage before adopting
- IF multiple approaches coexist in the repository → THEN identify the majority pattern and make a deliberate choice — selecting whichever is nearest is insufficient
- IF adopting an external dependency (library, plugin, SDK) → THEN verify repository-wide usage and compatibility evidence; when that evidence cannot determine the required version, record the unresolved version decision and the evidence needed to settle it
- IF following an existing pattern → THEN state the reason for following it when an alternative exists (e.g., consistency with surrounding code, avoiding breaking changes, pending coordinated update)
Principle
Nearby code is a starting point for investigation, not a sufficient basis for adoption. Verify that what you reference is representative of the repository's conventions and current best practices before using it as a model.
Performance Considerations
Optimization Approach
- Measure first: Profile before optimizing
- Focus on algorithms: Algorithmic complexity > micro-optimizations
- Use appropriate data structures: Choose based on access patterns
- Resource management: Handle memory, connections, and files properly
When to Optimize
- After identifying actual bottlenecks through profiling
- When performance issues are measurable
- Optimize only after measurable bottlenecks are identified, not during initial development
Code Organization
Structural Principles
- Group related functionality: Keep related code together
- Separate concerns: Domain logic, data access, presentation
- Consistent naming: Follow project conventions
- Module cohesion: High cohesion within modules, low coupling between
File Organization
- One primary responsibility per file
- Logical grouping of related functions/classes
- Clear folder structure reflecting architecture
- Split a file when it contains independently changing respo