principles

Related Skills

• Detected a code smell (long method, feature envy)? → Use refactoring for specific techniques
• Need a specific pattern (Strategy, Factory)? → Use design-patterns for selection and implementation
• Deciding which architectural layer or structure code belongs in? → Use architecture

Applicability Rubric

| Condition | Pass | Fail | |-----------|------|------| | New feature from scratch | Building without existing reference | Modifying existing code | | Design trade-off | Choosing between competing approaches | Implementation path is clear | | Interface/boundary design | Defining class responsibilities or contracts | Internal implementation detail | | Dependency structure | Deciding coupling and injection strategy | No dependency decisions |

Apply when: Any condition passes Do NOT apply when: The task is purely about restructuring existing code (use refactoring) or detecting code smells (use refactoring)

Core Principles

SOLID

| Principle | Description | Violation Sign | |-----------|-------------|----------------| | Single Responsibility | One reason to change | Class does too many things | | Open/Closed | Open for extension, closed for modification | Frequent changes to existing code | | Liskov Substitution | Subtypes must be substitutable | Type checks or conditional logic on types | | Interface Segregation | Many specific interfaces over one general | Clients implement unused methods | | Dependency Inversion | Depend on abstractions, not concretions | Direct instantiation of dependencies |

KISS (Keep It Simple, Stupid)

• Prefer straightforward solutions
• Avoid unnecessary complexity
• Write code that's easy to understand
• If it's hard to explain, it's too complex

DRY (Don't Repeat Yourself)

• Extract repeated logic into functions
• BUT: Premature abstraction is worse than duplication
• Rule of three: Abstract after third repetition
• Accept some duplication for clarity

YAGNI (You Aren't Gonna Need It)

• Don't build features until needed
• Avoid speculative generality
• Solve today's problem, not tomorrow's

Commenting

• Library / shared module public API: doc comment states intent and when to reach for it
• Application code: names and call sites carry the intent
• Private method: comment only when a value references something external (RFC code, control byte, ticket ID)
• A comment that restates the code in prose: extract a method whose name carries the meaning

Module type (application vs library) decides which default applies — see architecture Module Type.

Completion Rubric

Use the Violation Sign column in the SOLID table above as the primary checklist. Additionally verify:

| Criterion | Pass | Fail | |-----------|------|------| | Describable | Each class/function describable in one sentence | Needs a paragraph to explain | | Simplest solution | Chosen approach is the simplest that works | Over-engineered for hypothetical needs | | Dependencies injected | High-level modules depend on abstractions | Direct instantiation of concretions |

Scope Boundary

This skill addresses design-level decisions (abstraction level, coupling, interface shape). For code-level restructuring (long methods, duplicated code, feature envy), use the refactoring skill — it has specific techniques and safe steps for each smell.