xonecas.io
56101
Df

dotfiles / commit 1b2afe6

feat(skills): add good programming principles guidance

Sean2026-01-29 1b2afe6d8e53fe348a96d3ba81592cf1d9a32e0c parent 01f356d

1 file changed

opencode/skills/good-programming-principles/SKILL.md+89−0
@@ -0,0 +1,89 @@
1+---
2+name: good-programming-principles
3+description: Practical principles for simple, maintainable, resilient code.
4+version: 0.0.0
5+---
6+
7+# Good Programming Principles
8+
9+These principles reduce complexity, improve maintainability, and keep scope under control. Apply them together, but avoid dogma.
10+
11+## KISS (Keep It Simple, Stupid)
12+
13+- Favor the simplest design that solves the current problem.
14+- Prefer clarity over cleverness; optimize for readability.
15+- Reduce moving parts: fewer layers, fewer options, fewer states.
16+- Validate complexity with evidence (performance, scale, constraints).
17+
18+Sources:
19+- https://en.wikipedia.org/wiki/KISS_principle
20+- https://www.interaction-design.org/literature/topics/keep-it-simple-stupid
21+
22+## DRY (Don't Repeat Yourself)
23+
24+- Keep a single source of truth for logic, rules, and data.
25+- Remove copy-paste by extracting shared functions or modules.
26+- Avoid premature abstraction; small duplication can be acceptable if it preserves clarity.
27+- Consider AHA (Avoid Hasty Abstractions): abstract when duplication becomes a barrier and the abstraction's shape is clear.
28+
29+Sources:
30+- https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
31+- The Pragmatic Programmer (1999) by Andrew Hunt & David Thomas, ISBN 978-0-201-61622-4
32+- http://principles-wiki.net/principles:don_t_repeat_yourself
33+
34+## YAGNI (You Aren't Gonna Need It)
35+
36+- Build for current requirements, not hypothetical ones.
37+- Defer generalization until you have a concrete use case.
38+- Prefer small extension points over speculative flexibility.
39+- Originated from Extreme Programming (XP); works best with continuous refactoring and testing.
40+
41+Sources:
42+- https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it
43+- http://ronjeffries.com/xprog/articles/practices/pracnotneed/ (Ron Jeffries, XP co-founder)
44+- Extreme Programming Installed (2001) by Ron Jeffries et al., ISBN 0-201-70842-6
45+
46+## Feature Creep
47+
48+- Uncontrolled scope growth harms focus, quality, and timelines.
49+- Define and protect the minimum valuable feature set.
50+- Add features only with clear user value and acceptable cost.
51+
52+Sources:
53+- https://en.wikipedia.org/wiki/Feature_creep
54+- IEEE: "Toward preprototype user acceptance testing" (Davis & Venkatesh, 2004) - identifies feature creep as top cause of cost/schedule overruns
55+
56+## Overengineering
57+
58+- Extra complexity beyond the problem size increases risk and slows delivery.
59+- Choose the smallest solution that meets real constraints.
60+- Avoid unnecessary frameworks, abstractions, or configurability.
61+- Use measurements to justify optimization or architecture changes.
62+
63+Sources:
64+- https://en.wikipedia.org/wiki/Overengineering
65+- NASA Software Engineering Handbook - lists excessive features in top 10 development risks
66+- Harvard Business Review: "Defeating Feature Fatigue" (Rust, Thompson & Hamilton, 2006)
67+
68+## SOLID
69+
70+Introduced by Robert C. Martin; acronym coined by Michael Feathers (c. 2004).
71+
72+- Single Responsibility: one reason to change; keep modules focused.
73+- Open/Closed: extend via new code, avoid modifying stable paths.
74+- Liskov Substitution: derived types must work in place of base types.
75+- Interface Segregation: small, specific interfaces; avoid fat contracts.
76+- Dependency Inversion: depend on abstractions, invert control at boundaries.
77+
78+Sources:
79+- https://en.wikipedia.org/wiki/SOLID
80+- "Design Principles and Design Patterns" (Robert C. Martin, 2000): https://staff.cs.utu.fi/~jounsmed/doos_06/material/DesignPrinciplesAndPatterns.pdf
81+- Clean Architecture (2017) by Robert C. Martin, ISBN 978-0-13-449416-6
82+- https://www.baeldung.com/solid-principles
83+
84+## Applying the Principles
85+
86+- Start with KISS and YAGNI; keep scope tight and solutions simple.
87+- Refactor toward DRY when duplication is real and stable.
88+- Use SOLID as a refactoring lens, not a starting template.
89+- Guard against feature creep and overengineering with explicit scope checks.