ahonn Programming Philosophy and Quality Standards
Core Philosophy
- Code is primarily written for humans to read and maintain; machine execution is a by-product
- Priority: Readability & Maintainability > Correctness > Performance > Code length
- Follow idiomatic practices of each language community
Complexity Management
Complexity = Dependencies + Obscurity
Symptoms to Watch For
| Symptom | Description |
|---|---|
| Change Amplification | Small changes require modifications in many places |
| Cognitive Load | Developers need excessive information to complete tasks |
| Unknown Unknowns | Unclear what code needs modification (worst symptom) |
Mitigation Strategies
- "Zero tolerance" for incremental complexity growth
- Invest time upfront in design
- Avoid tactical shortcuts that create technical debt
Modular Design Principles
Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam. Hide design decisions inside implementations; combat over-specialization and "classitis". For the full vocabulary (module, interface, seam, adapter, depth, leverage, locality) and design procedures, use the codebase-design skill.
Code Smells to Watch For
Proactively identify and flag:
- Duplicated logic / copy-paste code
- Over-tight coupling or circular dependencies
- Fragile designs where one change breaks unrelated parts
- Unclear intent, confused abstractions, vague naming
- Over-engineering without real benefit
When identifying code smells:
- Explain the problem concisely
- Provide 1–2 refactoring directions with pros/cons
Error Handling Strategy
- Define errors out of existence — design APIs with no exceptions when possible
- Mask exceptions at low levels to protect higher layers
- Aggregate exceptions with general-purpose handlers
- Just crash for rare, unrecoverable errors
Comment Standards
- Self-documenting code first — improve naming and structure before adding comments
- WHY over WHAT — comments explain intent and reasoning, not mechanics
- Reduce cognitive load — make implicit knowledge explicit
- Zero redundancy — never restate what code already expresses
DO comment: design decisions/trade-offs, non-obvious behavior, interface contracts, gotchas/edge cases, cross-module dependencies
DON'T comment: self-evident code, well-named variables/functions, standard patterns, implementation details visible in code
When modifying code:
- Remove comments that restate what code does
- Keep comments that explain WHY
- Add comments only for non-obvious behavior or design decisions
- Update stale comments when code changes invalidate them
- Never add comments just to fill space or appear thorough
Comment Cleanup Procedure
When invoked directly with a file path (/code-quality <file>), clean up its comments per the Comment Standards above:
- Read the file to understand its purpose and structure
- Suggest naming improvements that make code self-documenting, applying them if safe
- Remove comments that restate code, add noise, or are outdated
- Add comments only where they explain non-obvious behavior, design decisions, complex algorithms, or essential interface contracts
- Leave the file cleaner than found