coding-rules · diff
git:20251231.cb53cf6 to git:20260829.876a214
39 added, 103 removed. Audit A to A.
---
name: coding-rules
- description: "Applies coding standards for clean, maintainable code. Use when: writing functions, handling errors, refactoring, or reviewing code style."
+ description: "Applies repository-aware rules for maintainable implementation, contracts, errors, and refactoring. Use when writing or modifying code."
---
# Development Rules
- ## Language-Specific References
-
- For language-specific rules, also read:
- - **TypeScript**: [references/typescript.md](references/typescript.md)
-
- ## Basic Principles
+ ## Language and Repository Rules
- ✅ **Aggressive Refactoring**
- - Continuously improve code structure and readability
- - Make code changes in small, safe steps
- - Prioritize maintainability over initial implementation speed
+ Use the repository's formatter, linter, type system, naming conventions, and representative code patterns. Read a language reference only when it applies:
- ❌ **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
+ - **TypeScript**: [references/typescript.md](references/typescript.md)
- ## Comment Writing Rules
+ Repository contracts and accepted design decisions take precedence over generic style preferences.
- - **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
+ ## Minimal Change
- ## Function Design
+ - Implement the confirmed outcome through existing mechanisms where sufficient.
+ - Keep unrelated cleanup and optional hardening outside the change.
+ - Remove unused code encountered inside the changed responsibility when evidence shows no current consumer remains.
+ - Introduce an abstraction only when current callers share responsibility and change pressure.
- **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*
+ ## Functions and Interfaces
- **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
+ - Keep one coherent responsibility per function or module.
+ - Use the language's idiomatic parameter and data-shape conventions.
+ - Make external dependencies and side effects visible at the appropriate boundary.
+ - Preserve public and shared contracts unless the approved scope changes them.
+ - Prefer simple control flow; refactor complexity when it obscures behavior or error handling.
## 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
+ - Preserve actionable error context across boundaries.
+ - Convert errors only where the receiving layer needs a different contract.
+ - Avoid logging the same error at every layer.
+ - Keep secrets, credentials, and unnecessary personal data out of logs and messages.
+ - Add fallback behavior only when a current requirement defines the degraded result.
- **Implementation Procedure**
- 1. Understand Current State
- 2. Make Gradual Changes
- 3. Verify Behavior
- 4. Final Validation
+ ## Comments and Documentation
- **Priority Order**
- 1. Duplicate Code Removal
- 2. Large Function Division
- 3. Complex Conditional Branch Simplification
- 4. Architecture Improvement
+ - Explain non-obvious intent, constraints, or trade-offs.
+ - Keep comments timeless and remove obsolete or commented-out code.
+ - Update documentation when an affected consumer would otherwise act on stale information.
- ## Performance Considerations
+ ## Refactoring
- **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
+ 1. Confirm the observable behavior and focused proof.
+ 2. Make the smallest coherent structural change.
+ 3. Run affected verification.
+ 4. Continue only when another current problem remains.
- **Resource Management**
- - Properly close files, connections, and other resources
- - Be mindful of memory leaks in long-running applications
- - Use efficient algorithms for data processing
+ ## Performance and Resources
- ## Code Organization
+ - Measure a demonstrated bottleneck before optimizing.
+ - Use resource-lifecycle and data-structure patterns appropriate to the language and repository.
+ - Add caching, concurrency, batching, or monitoring only when a current requirement or measured problem justifies it.
- **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
+ ## Completion Check
- **Modularity**
- - Write small, focused modules/functions
- - Minimize dependencies between modules
- - Use clear interfaces between components
- - Follow single responsibility principle
+ - The implementation follows representative repository patterns or documents a necessary deviation.
+ - Added structure has a current consumer and purpose.
+ - Errors remain observable without duplicative logging or silent fallback.
+ - Applicable repository checks pass.