58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
|
# Philosophy of Software Design — Codex Skill
|
||
|
|
|
||
|
|
## Goal
|
||
|
|
|
||
|
|
Design software so it is easy to understand, change, and extend.
|
||
|
|
|
||
|
|
## Core rule
|
||
|
|
|
||
|
|
Optimize for **lower complexity**, not just fewer lines of code.
|
||
|
|
|
||
|
|
## Recommendations
|
||
|
|
|
||
|
|
1. **Prefer deep modules.** Hide substantial complexity behind a small, clean interface.
|
||
|
|
2. **Keep interfaces simple.** Expose only what callers truly need.
|
||
|
|
3. **Hide information aggressively.** Do not leak implementation details across module boundaries.
|
||
|
|
4. **Do not pass complexity around.** Solve it where it belongs instead of pushing it onto callers.
|
||
|
|
5. **Make the important things obvious.** Favor clarity over cleverness.
|
||
|
|
6. **Minimize special cases.** Exceptions, one-off rules, and edge-paths increase cognitive load.
|
||
|
|
7. **Design invalid states out of the system.** Prevent mistakes through better APIs and structure.
|
||
|
|
8. **Separate mechanism from policy.** Keep reusable machinery distinct from usage-specific decisions.
|
||
|
|
9. **Use precise names.** Good naming reduces system-wide confusion.
|
||
|
|
10. **Write comments that add information.** Explain why, constraints, invariants, and intent — not what the code already says.
|
||
|
|
11. **Document interfaces clearly.** State guarantees, expectations, and failure modes.
|
||
|
|
12. **Refactor early when complexity starts rising.** Small structural fixes compound.
|
||
|
|
13. **Be consistent.** Similar things should look and behave similarly.
|
||
|
|
14. **Protect layering.** Higher-level code should not depend on unnecessary low-level details.
|
||
|
|
15. **Write for future readers.** Assume the next editor needs the system to be legible fast.
|
||
|
|
|
||
|
|
## Decision filter
|
||
|
|
|
||
|
|
Before adding code, ask:
|
||
|
|
|
||
|
|
- Does this reduce or increase cognitive load?
|
||
|
|
- Does this make future changes easier?
|
||
|
|
- Is the interface smaller and clearer?
|
||
|
|
- Am I hiding complexity or spreading it?
|
||
|
|
- Will another engineer understand this quickly?
|
||
|
|
|
||
|
|
## Anti-patterns
|
||
|
|
|
||
|
|
Avoid:
|
||
|
|
|
||
|
|
- clever abstractions with leaky interfaces
|
||
|
|
- shallow modules that add indirection without hiding complexity
|
||
|
|
- comments that merely restate code
|
||
|
|
- special cases added without simplifying the general model
|
||
|
|
- dependency tangles across layers
|
||
|
|
|
||
|
|
## Output standard
|
||
|
|
|
||
|
|
When generating or editing code:
|
||
|
|
|
||
|
|
- favor simple, stable interfaces
|
||
|
|
- keep module responsibilities crisp
|
||
|
|
- eliminate unnecessary branching and exceptions
|
||
|
|
- choose clarity over brevity when they conflict
|
||
|
|
- leave the codebase easier to change than before
|