docs: Add design pattern examples and update submodule
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
Some checks failed
Test Suite / unit-tests (3.11) (push) Has been cancelled
Test Suite / unit-tests (3.12) (push) Has been cancelled
Test Suite / integration-tests (push) Has been cancelled
Test Suite / e2e-tests (push) Has been cancelled
Test Suite / performance-tests (push) Has been cancelled
Test Suite / code-quality (push) Has been cancelled
Test Suite / security-scan (push) Has been cancelled
Test Suite / test-summary (push) Has been cancelled
Add Design Pattern Documentation: - Add CopyFirstMigration.md - Documents the copy-first migration principle used in the TestDrive-JSUI capability migration - Add DontRepeatYourself.md - Documents the DRY principle - Add DesignPrincipleSchema.json - JSON schema for design pattern documentation Update Submodule: - Update testdrive-jsui submodule pointer to include Phase 4 documentation (migration completion with legacy file cleanup) Context: These design pattern examples document the principles applied during the successful TestDrive-JSUI migration, which serves as a reference implementation of the copy-first migration pattern. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
160
examples/design-patterns/DontRepeatYourself.md
Normal file
160
examples/design-patterns/DontRepeatYourself.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# Design Principle: Don’t Repeat Yourself (DRY)
|
||||
|
||||
## Meta
|
||||
- **Name:** Don’t Repeat Yourself
|
||||
- **ShortName:** DRY
|
||||
- **Version:** 0.1
|
||||
- **Status:** Stable
|
||||
- **Tags:** maintainability, refactoring, architecture, quality
|
||||
- **RelatedPrinciples:** Single Responsibility, YAGNI, Separation of Concerns
|
||||
|
||||
---
|
||||
|
||||
## Intent
|
||||
Reduce maintenance cost and behavioral drift by ensuring that each piece of
|
||||
knowledge, rule, or decision logic has a single authoritative representation
|
||||
in the codebase.
|
||||
|
||||
---
|
||||
|
||||
## CoreStatement
|
||||
A codebase violates DRY when the same knowledge is expressed in multiple places
|
||||
such that a change would require edits in more than one location or risks
|
||||
inconsistent behavior.
|
||||
|
||||
---
|
||||
|
||||
## Scope
|
||||
|
||||
### InScope
|
||||
- Business rules and decision logic
|
||||
- Algorithms and validation logic
|
||||
- Data schemas, DTOs, and field definitions
|
||||
- Configuration values and feature flags
|
||||
- Repeated workflows or orchestration logic
|
||||
- Test setup and invariant test scenarios
|
||||
|
||||
### OutOfScope
|
||||
- Superficial textual similarity without shared meaning
|
||||
- Intentional duplication for isolation or clarity
|
||||
- Early-stage exploratory code where abstractions are not yet clear
|
||||
- Performance-driven duplication with explicit justification
|
||||
|
||||
---
|
||||
|
||||
## InterpretationGuidelines
|
||||
|
||||
### What “Repeat” Means
|
||||
DRY is about **duplication of knowledge**, not duplication of text.
|
||||
|
||||
Examples of knowledge duplication:
|
||||
- The same validation rule implemented in multiple services
|
||||
- Identical conditional logic controlling the same behavior
|
||||
- The same data structure defined independently in multiple modules
|
||||
|
||||
### Common Misinterpretations
|
||||
- “Any repeated code is bad” (false)
|
||||
- “DRY means maximum abstraction” (false)
|
||||
- “Utility modules automatically improve DRY” (often false)
|
||||
|
||||
---
|
||||
|
||||
## DetectionHeuristics
|
||||
|
||||
### Structural Signals
|
||||
- Functions with highly similar bodies and signatures
|
||||
- Repeated constants, strings, regexes, or SQL fragments
|
||||
- Parallel modules with mirrored internal structure
|
||||
|
||||
### Semantic Signals
|
||||
- Identical error messages or validation rules in different layers
|
||||
- Repeated mapping logic between the same concepts
|
||||
- Copy-paste variations differing only in naming
|
||||
|
||||
### Change-Cost Signals
|
||||
- A requirement change touches multiple files for the same reason
|
||||
- Fixes applied in one location but missing in others
|
||||
- Tests failing inconsistently after partial updates
|
||||
|
||||
---
|
||||
|
||||
## DiagnosticQuestions
|
||||
1. Is this duplication representing the same rule or policy?
|
||||
2. If this rule changes, how many places must be updated?
|
||||
3. Is the duplicated logic stable or likely to evolve?
|
||||
4. Are the differences intentional or accidental?
|
||||
5. Where is the natural “source of truth” for this knowledge?
|
||||
6. Would abstraction reduce or increase cognitive load?
|
||||
|
||||
---
|
||||
|
||||
## RecommendedActions
|
||||
|
||||
### Low-Risk Refactors
|
||||
- Extract constants or configuration values
|
||||
- Centralize literals and error messages
|
||||
- Introduce shared test fixtures or helpers
|
||||
|
||||
### Medium-Risk Refactors
|
||||
- Extract pure helper functions
|
||||
- Introduce shared domain services or modules
|
||||
- Unify schema/type definitions
|
||||
|
||||
### High-Risk Refactors
|
||||
- Introduce strategy/template patterns
|
||||
- Merge parallel subsystems
|
||||
- Redesign domain boundaries to align ownership of rules
|
||||
|
||||
---
|
||||
|
||||
## AcceptanceCriteria
|
||||
- Each rule or behavior has a single authoritative implementation
|
||||
- Required changes affect fewer locations than before
|
||||
- Naming reflects domain meaning, not technical convenience
|
||||
- Tests pass without behavior regression
|
||||
- Coupling does not increase unintentionally
|
||||
|
||||
---
|
||||
|
||||
## AntiPatterns
|
||||
- “God” utility modules with unrelated helpers
|
||||
- Over-generalized abstractions with many parameters
|
||||
- Shared code across domains that should evolve independently
|
||||
- Premature abstraction of coincidental similarities
|
||||
- Hiding meaningful differences behind generic interfaces
|
||||
|
||||
---
|
||||
|
||||
## Tradeoffs
|
||||
Applying DRY may:
|
||||
- Increase indirection
|
||||
- Reduce local readability
|
||||
- Introduce coupling between modules
|
||||
|
||||
These costs are acceptable only when outweighed by reduced change cost
|
||||
and increased behavioral consistency.
|
||||
|
||||
---
|
||||
|
||||
## AgentUsage
|
||||
|
||||
### When to Apply This Lens
|
||||
- During refactoring or maintenance work
|
||||
- When change requests repeatedly touch similar code
|
||||
- When bugs recur due to partial updates
|
||||
- During architectural consolidation
|
||||
|
||||
### When to Suspend This Lens
|
||||
- During early exploration or prototyping
|
||||
- When future variability is unclear
|
||||
- When isolation is more valuable than reuse
|
||||
|
||||
### Expected Agent Output
|
||||
- Identified DRY violations with locations
|
||||
- Rationale for why duplication matters
|
||||
- Volatility assessment (stable vs evolving)
|
||||
- Recommended refactor type and target
|
||||
- Risk notes and minimal patch sequence
|
||||
|
||||
xxx
|
||||
|
||||
Reference in New Issue
Block a user