coding-rules

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

Development Rules

MUST READ (project)

• docs/dev/GUARDRAILS.md — canonical rules (output contract, style/units when applicable)
• docs/style/STYLE_GUIDE.md — style guide

MUST NOT (style)

• No !important; no absolute units in CSS/SCSS; no constant inline styles; no patching docs to justify violations

---

Language-Specific References

For language-specific rules, also read:

• TypeScript: references/typescript.md

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