/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

1. **Maintainability over Speed**: Prioritize long-term code health over initial development velocity 2. **Simplicity First**: Choose the simplest solution that meets requirements (YAGNI principle) 3. **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. 4. **Explicit over Implicit**: Make intentions clear through code structure and naming 5. **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

Existing code relates to a change in two ways. Code that depends on it — callers, consumers, configuration — is reached through references to the changed code. Code that already holds the same responsibility may share no name or reference with it; reach it through position and role (sibling features, files with the same role in the same layer, shared layers) and through the input it takes and the purpose it serves, then compare their logic to judge whether the responsibility is the same.

When alternatives coexist, choose the pattern from responsibility, contract, lifecycle and repository usage rather than proximity or global popularity alone. Record the evidence only when it changes the choice.

Expand to all known consumers for a changed public, shared, serialized or persistent contract whose compatibility depends on them. Stop when the candidates that could change implementation or proof have been read and judged; a search with no match shows only that the search found nothing. Resolve versions from applicable manifests and usage; record a specific limitation only when required compatibility evidence remains unavailable.

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 responsibilit