{
"version": "2.2.0",
"description": "Enriched relational mapping with bidirectional links and code smells",
"last_updated": "2026-04-29",
"DP-001": {
"id": "DP-001",
"type": "pattern",
"file_path": "design-patterns/creational/abstract-factory.md",
"title": "Abstract Factory",
"category": "creational",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-042-I"
],
"violates": [],
"related_to": [
"DP-002",
"DP-003",
"DP-004",
"DP-005",
"DP-007",
"DP-010",
"DP-011"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Code must work with various product families"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Eliminates tight coupling between",
"Guarantees compatible products from the same factory"
],
"drawbacks": [
"Introduces additional interfaces and classes, increasing code complexity",
"May be unnecessarily elaborate for simpler scenarios"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-002": {
"id": "DP-002",
"type": "pattern",
"file_path": "design-patterns/creational/builder.md",
"title": "Builder",
"category": "creational",
"tags": [],
"relations": {
"solves": [
"SMELL-04"
],
"enforces": [],
"violates": [],
"related_to": [
"DP-001",
"DP-003",
"DP-004",
"DP-005",
"DP-007",
"DP-008"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When constructing complex objects with many optional parameters or configuration steps",
"When you need to create different representations of the same object",
"When telescoping constructors are proliferating"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Step-by-step"
],
"drawbacks": [
"Increased overall code complexity through multiple new classes"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-003": {
"id": "DP-003",
"type": "pattern",
"file_path": "design-patterns/creational/factory-method.md",
"title": "Factory Method",
"category": "creational",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-D",
"LAW-042-O"
],
"violates": [],
"related_to": [
"DP-001",
"DP-002",
"DP-004",
"DP-015",
"DP-021"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When a class cannot anticipate the type of objects it must create",
"When you want subclasses to decide which objects to create",
"When you need to delegate object creation to subclasses"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-004": {
"id": "DP-004",
"type": "pattern",
"file_path": "design-patterns/creational/prototype.md",
"title": "Prototype",
"category": "creational",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"DP-001",
"DP-002",
"DP-003",
"DP-005",
"DP-008",
"DP-009",
"DP-014",
"DP-017",
"DP-011"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Code shouldn't depend on concrete object classes"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Decouples code from"
],
"drawbacks": [
"Cloning objects with circular references becomes complicated"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-005": {
"id": "DP-005",
"type": "pattern",
"file_path": "design-patterns/creational/singleton.md",
"title": "Singleton",
"category": "creational",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [
"DP-001",
"DP-002",
"DP-004",
"DP-010",
"DP-011"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- A class should have only one instance accessible to all clients (e.g., shared database objects)"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Provides global access to that instance",
"Guarantees single class instance existence",
"Lazy initialization—objects are created only when first requested"
],
"drawbacks": [
"Complicates unit testing due to private constructors and static method overriding limitations",
"Violates the Single Responsibility Principle (solves two problems simultaneously)",
"Requires special multithreaded handling to prevent multiple instances",
"Can mask poor design patterns and excessive component interdependence"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-006": {
"id": "DP-006",
"type": "pattern",
"file_path": "design-patterns/structural/adapter.md",
"title": "Adapter",
"category": "structural",
"tags": [],
"relations": {
"solves": [
"SMELL-11"
],
"enforces": [
"LAW-042-L",
"LAW-042-I"
],
"violates": [],
"related_to": [
"DP-007",
"DP-009",
"DP-010",
"DP-012",
"DP-019",
"DP-020"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Existing classes have incompatible interfaces requiring integration"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Separates interface/data"
],
"drawbacks": [
"Sometimes simpler to modify the service class directly",
"Increases overall code complexity through additional interfaces and classes"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-007": {
"id": "DP-007",
"type": "pattern",
"file_path": "design-patterns/structural/bridge.md",
"title": "Bridge",
"category": "structural",
"tags": [],
"relations": {
"solves": [
"SMELL-03"
],
"enforces": [
"LAW-042-O"
],
"violates": [],
"related_to": [
"DP-001",
"DP-002",
"DP-006"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Dividing monolithic classes with multiple functionality variants"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-008": {
"id": "DP-008",
"type": "pattern",
"file_path": "design-patterns/structural/composite.md",
"title": "Composite",
"category": "structural",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O",
"LAW-042-L"
],
"violates": [],
"related_to": [
"DP-002",
"DP-004",
"DP-015"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Your application models tree-like structures"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Simplifies handling complex tree structures through polymorphism",
"Follows Open/Closed Principle—new element types integrate without breaking existing code"
],
"drawbacks": [
"Can complicate the interface unnecessarily",
"Creating unified interfaces for dissimilar functionality may require overgeneralization"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-009": {
"id": "DP-009",
"type": "pattern",
"file_path": "design-patterns/structural/decorator.md",
"title": "Decorator",
"category": "structural",
"tags": [],
"relations": {
"solves": [
"SMELL-03"
],
"enforces": [
"LAW-042-O",
"LAW-042-L"
],
"violates": [],
"related_to": [
"DP-004",
"DP-006"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Assigning extra behaviors at runtime without breaking existing code"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Supports Single Responsibility Principle",
"Combine multiple behaviors through wrapping",
"Extend objects without subclassing",
"Add/remove responsibilities at runtime"
],
"drawbacks": [
"Initial configuration code can appear complex",
"Behavior may depend on decorator order",
"Difficult removing specific wrappers from stack"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-010": {
"id": "DP-010",
"type": "pattern",
"file_path": "design-patterns/structural/facade.md",
"title": "Facade",
"category": "structural",
"tags": [],
"relations": {
"solves": [
"SMELL-01",
"SMELL-21"
],
"enforces": [
"LAW-041",
"LAW-001",
"LAW-042-D"
],
"violates": [],
"related_to": [
"DP-001",
"DP-005",
"DP-006",
"DP-012",
"DP-016"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- You need straightforward access to complex subsystems"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Isolates client code from subsystem complexity"
],
"drawbacks": [
"Facades can become \"god objects\" tightly coupled to numerous application classes"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-011": {
"id": "DP-011",
"type": "pattern",
"file_path": "design-patterns/structural/flyweight.md",
"title": "Flyweight",
"category": "structural",
"tags": [],
"relations": {
"solves": [
"SMELL-14"
],
"enforces": [
"LAW-040"
],
"violates": [],
"related_to": [
"DP-005",
"DP-001",
"DP-004",
"RF-021"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Applications spawn huge numbers of similar objects"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Significant RAM savings with numerous similar objects"
],
"drawbacks": [
"May trade memory for CPU cycles during recalculation of context data",
"Increased code complexity confuses team members about state separation"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-012": {
"id": "DP-012",
"type": "pattern",
"file_path": "design-patterns/structural/proxy.md",
"title": "Proxy",
"category": "structural",
"tags": [],
"relations": {
"solves": [
"SMELL-14"
],
"enforces": [
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"DP-006",
"DP-010"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Controls access to the original object",
"Adds behavior (caching, lazy loading, access control) without modifying the real object",
"Manages lifecycle of expensive resources"
],
"drawbacks": [
"Potential response delays from service",
"Increased code complexity from additional classes"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-013": {
"id": "DP-013",
"type": "pattern",
"file_path": "design-patterns/behavioral/chain-of-responsibility.md",
"title": "Chain Of Responsibility",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O",
"LAW-042-S"
],
"violates": [],
"related_to": [
"DP-014",
"DP-016"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Processing different request types in various ways with unknown sequences beforehand"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Decouples sender from receiver, reducing direct dependencies",
"Allows dynamic chaining of handlers at runtime",
"Simplifies individual handler logic by giving each a single responsibility"
],
"drawbacks": [
"Requests may reach the chain's end unhandled"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-014": {
"id": "DP-014",
"type": "pattern",
"file_path": "design-patterns/behavioral/command.md",
"title": "Command",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O",
"LAW-042-S"
],
"violates": [],
"related_to": [
"DP-004",
"DP-013",
"DP-016",
"DP-017",
"DP-019",
"DP-020",
"DP-022"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When you need to parameterize objects with operations",
"When you need to queue, schedule, or undo operations",
"When you want to decouple request sender from receiver"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-015": {
"id": "DP-015",
"type": "pattern",
"file_path": "design-patterns/behavioral/iterator.md",
"title": "Iterator",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-02"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"DP-003",
"DP-008",
"DP-017",
"DP-019",
"DP-022"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When you need to traverse a collection without exposing its internal structure",
"When you need multiple simultaneous traversals of a collection",
"When you want a uniform interface for different collection types"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Enables parallel iteration over the same collection",
"Allows delayed and resumable iteration",
"Supports Open/Closed Principle for new collection and iterator types",
"Upholds Single Responsibility Principle by extracting traversal logic"
],
"drawbacks": [
"May be excessive for simple collections",
"Potentially less efficient than direct element access in specialized collections"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-016": {
"id": "DP-016",
"type": "pattern",
"file_path": "design-patterns/behavioral/mediator.md",
"title": "Mediator",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-19"
],
"enforces": [
"LAW-042-S",
"LAW-043",
"LAW-001",
"LAW-042-D"
],
"violates": [],
"related_to": [
"DP-010",
"DP-013",
"DP-014",
"DP-018"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When a set of objects communicate in complex but well-defined ways",
"When reusing an object is difficult because it refers to many other objects",
"When behavior distributed between classes should be customizable without subclassing"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Supports Open/Closed Principle through new mediator implementations",
"Reduces component coupling",
"Enhances component reusability",
"Improves Single Responsibility: \"extract the communications between various components into a single"
],
"drawbacks": [
"Mediators can evolve into \"God Objects\" over time, accumulating excessive responsibilities"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-017": {
"id": "DP-017",
"type": "pattern",
"file_path": "design-patterns/behavioral/memento.md",
"title": "Memento",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"DP-004",
"DP-014",
"DP-015",
"DP-019"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When you need to save and restore an object's state without violating encapsulation",
"When direct access to the object's fields would expose implementation details",
"When you need undo/rollback functionality"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Simplifies originator code by delegating history management",
"Maintains encapsulation during state capture"
],
"drawbacks": [
"Caretakers must track originator lifecycle to dispose obsolete mementos",
"Dynamic languages (PHP, Python, JavaScript) cannot guarantee memento immutability",
"Excessive RAM consumption from frequent memento creation"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-018": {
"id": "DP-018",
"type": "pattern",
"file_path": "design-patterns/behavioral/observer.md",
"title": "Observer",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-19"
],
"enforces": [
"LAW-042-O",
"LAW-043",
"LAW-042-D"
],
"violates": [],
"related_to": [
"DP-016"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- State changes in one object require updating others with an unknown or dynamic set"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Follows Open/Closed Principle—new subscribers integrate without modifying publisher code",
"Runtime relationship establishment between objects"
],
"drawbacks": [
"Subscribers receive notifications in random order"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-019": {
"id": "DP-019",
"type": "pattern",
"file_path": "design-patterns/behavioral/state.md",
"title": "State",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O",
"LAW-042-S",
"LAW-042-L"
],
"violates": [],
"related_to": [
"DP-006",
"DP-014",
"DP-015",
"DP-017"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Objects behave differently based on internal state"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Eliminates bulky conditional state-checking logic",
"Localizes state-specific behavior into separate classes",
"Makes state transitions explicit"
],
"drawbacks": [
"Can be excessive for simple state machines with few states"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-020": {
"id": "DP-020",
"type": "pattern",
"file_path": "design-patterns/behavioral/strategy.md",
"title": "Strategy",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O"
],
"violates": [],
"related_to": [
"DP-006",
"DP-014",
"DP-021",
"RF-037"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When you need to switch between different algorithms at runtime",
"When a class has many related behaviors defined in conditional statements",
"When you want to isolate algorithm implementation details from the code that uses it"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Runtime algorithm swapping capability",
"Open/Closed Principle compliance—add strategies without modifying",
"Composition replaces inheritance",
"Implementation isolation from usage code"
],
"drawbacks": [
"Unnecessary complexity for simple, stable algorithms",
"Modern languages with functional support may eliminate the need for extra classes",
"Clients must understand strategy differences to select appropriately"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-021": {
"id": "DP-021",
"type": "pattern",
"file_path": "design-patterns/behavioral/template-method.md",
"title": "Template Method",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-03"
],
"enforces": [
"LAW-040",
"LAW-042-L",
"LAW-042-O",
"LAW-001"
],
"violates": [],
"related_to": [
"DP-003",
"DP-020"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When subclasses must override specific algorithm steps while preserving overall structure",
"When you want to enforce an invariant algorithm skeleton",
"When you detect duplicated algorithm structure across subclasses"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Shared implementations",
"Clients override only necessary algorithm portions, minimizing impact from other modifications"
],
"drawbacks": [
"Risk of violating the Liskov Substitution Principle through step suppression",
"Limited client flexibility constrained by provided algorithm skeletons",
"Maintenance complexity increases with additional template steps"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"DP-022": {
"id": "DP-022",
"type": "pattern",
"file_path": "design-patterns/behavioral/visitor.md",
"title": "Visitor",
"category": "behavioral",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O",
"LAW-001"
],
"violates": [],
"related_to": [
"DP-014",
"DP-015"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"- Performing operations on all elements of complex structures (object trees)"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [
"Follows Open/Closed Principle—add behaviors without modifying classes",
"Visitors can accumulate information while traversing complex structures",
"Follows Single Responsibility—group related behaviors in visitor classes"
],
"drawbacks": [
"Visitors may lack access to private fields and methods",
"Must update all visitors when adding/removing element classes"
]
},
"source": {
"title": "Design Patterns: Elements of Reusable Object-Oriented Software",
"authors": [
"Erich Gamma",
"Richard Helm",
"Ralph Johnson",
"John Vlissides"
],
"year": 1994,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://www.oreilly.com/library/view/design-patterns-elements/0201633612/"
}
},
"RF-001": {
"id": "RF-001",
"type": "refactoring",
"file_path": "refactoring/composing-methods/extract-method.md",
"title": "Extract Method",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [
"SMELL-01",
"SMELL-04",
"SMELL-06",
"SMELL-09",
"SMELL-13",
"SMELL-16",
"SMELL-18",
"SMELL-21",
"SMELL-23"
],
"enforces": [
"LAW-040",
"LAW-041",
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-002",
"RF-003",
"RF-005"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method is too long or does more than one thing",
"A code block needs a comment to explain its purpose",
"You want to reuse a fragment of code in multiple places"
],
"when_not_to_use": [],
"symptoms": [
"Long Method",
"Duplicate Code",
"Feature Envy"
],
"benefits": [
"evident",
"Improved Readability:",
"Reduced Duplication:",
"Better Error Isolation:"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-002": {
"id": "RF-002",
"type": "refactoring",
"file_path": "refactoring/composing-methods/extract-variable.md",
"title": "Extract Variable",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"RF-001",
"RF-004"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A complex expression is hard to understand without explanation",
"The same expression is used multiple times in a method",
"You need to debug or log an intermediate value"
],
"when_not_to_use": [],
"symptoms": [
"Complex conditional or arithmetic expressions that require comments to understand",
"Repeated identical sub-expressions within a method body"
],
"benefits": [
"Names complex expressions, making code self-documenting",
"Simplifies debugging by giving intermediate values identifiable names",
"Makes it easier to extract the expression into a method later"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-003": {
"id": "RF-003",
"type": "refactoring",
"file_path": "refactoring/composing-methods/inline-method.md",
"title": "Inline Method",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [
"SMELL-12",
"SMELL-17"
],
"enforces": [],
"violates": [],
"related_to": [
"RF-001",
"RF-009",
"RF-005"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method body is as clear as its name and adds no abstraction value",
"Indirection through a trivial method obscures rather than clarifies",
"You need to refactor call sites to use a different method and the current one is in the way"
],
"when_not_to_use": [],
"symptoms": [
"Methods that consist of a single delegation call with no added logic",
"Readers must navigate through multiple trivial method calls to understand behavior"
],
"benefits": [
"Reduces unnecessary indirection and navigation overhead",
"Makes code more straightforward by removing trivial delegation layers",
"Can enable further refactorings by consolidating logic in one place"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-004": {
"id": "RF-004",
"type": "refactoring",
"file_path": "refactoring/composing-methods/inline-temp.md",
"title": "Inline Temp",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"RF-002",
"RF-008",
"RF-005"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A temporary variable holds a simple expression that is used only once",
"The temp variable interferes with other refactorings like Extract Method",
"The variable name adds no clarity beyond the expression itself"
],
"when_not_to_use": [],
"symptoms": [
"Temporary variables that are assigned once and used immediately",
"Temps that obscure rather than clarify the logic of a method"
],
"benefits": [
"Eliminates unnecessary temporary variables, reducing clutter",
"Often a prerequisite for applying Extract Method successfully",
"Makes the flow of data through a method more transparent"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-005": {
"id": "RF-005",
"type": "refactoring",
"file_path": "refactoring/composing-methods/remove-assignments-to-parameters.md",
"title": "Remove Assignments to Parameters",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-040",
"LAW-041",
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-001",
"RF-003",
"RF-004"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A temporary variable is used to cache a computed value that is needed in multiple places",
"You want to use the computed value from other methods in the same class",
"The computation is cheap enough that recomputing is acceptable"
],
"when_not_to_use": [],
"symptoms": [
"Long Method",
"Duplicate Code"
],
"benefits": [
"Makes computed values accessible across methods, not just within one",
"Eliminates the need to pass temporary variables as method parameters",
"Enables further refactorings by exposing the query as a method"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"LAW-001": {
"id": "LAW-001",
"type": "law",
"file_path": "software-engineering/teams/conways-law.md",
"title": "Conways Law",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"API designs naturally align with team dependencies and reporting lines",
"Cross-team collaboration tools and practices directly impact system integration approaches",
"Microservices adoption often requires reorganizing teams from function-based to domain-based structures",
"Companies restructuring to support cloud-native architectures must also restructure their teams"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "How Do Committees Invent?",
"authors": [
"Melvin Conway"
],
"year": 1968,
"publisher": "Datamation",
"license": "reference",
"url": "https://www.melconway.com/Home/Conways_Law.html"
}
},
"LAW-002": {
"id": "LAW-002",
"type": "law",
"file_path": "software-engineering/teams/brooks-law.md",
"title": "Brooks Law",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-004"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Task decomposition strategies are critical for determining parallelizability",
"Hiring practices should account for ramp-up time and productivity curves",
"Crisis staffing often backfires without proper planning and mentorship structure",
"Project management decisions during delays require caution before adding resources"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Mythical Man-Month",
"authors": [
"Fred Brooks"
],
"year": 1975,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Brooks%27s_law"
}
},
"LAW-003": {
"id": "LAW-003",
"type": "law",
"file_path": "software-engineering/teams/dunbars-number.md",
"title": "Dunbars Number",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Team scaling strategies should account for cognitive limits and relationship maintenance costs",
"Engineering teams typically split or restructure when exceeding 150-200 people",
"Startup cultures emphasizing \"everyone knows everyone\" are limited to roughly Dunbar's Number",
"Large organizations require more formal communication, documentation, and process"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Neocortex size as a constraint on group size in primates",
"authors": [
"Robin I.M. Dunbar"
],
"year": 1992,
"publisher": "Journal of Human Evolution",
"license": "reference",
"url": "https://doi.org/10.1016/0047-2484(92)90081-J"
}
},
"LAW-004": {
"id": "LAW-004",
"type": "law",
"file_path": "software-engineering/teams/ringelmann-effect.md",
"title": "Ringelmann Effect",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Code review processes must scale without becoming bottlenecks",
"Incentive systems should encourage individual accountability within team settings",
"Team size optimization becomes crucial for maintaining velocity",
"Decision-making structures should prevent diffusion of responsibility"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Recherches sur les moteurs animés: Travail de l'homme",
"authors": [
"Maximilien Ringelmann"
],
"year": 1913,
"publisher": "Annales de l'Institut National Agronomique, 2nd series, vol. 12",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Ringelmann_effect"
}
},
"LAW-005": {
"id": "LAW-005",
"type": "law",
"file_path": "software-engineering/teams/prices-law.md",
"title": "Prices Law",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Compensation and recognition should account for contribution distribution",
"Open-source projects typically have a small core of highly productive contributors",
"Engineering organizations should identify and nurture top performers",
"Knowledge and decision-making naturally concentrate; processes should acknowledge this"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Little Science, Big Science",
"authors": [
"Derek J. de Solla Price"
],
"year": 1963,
"publisher": "Columbia University Press",
"license": "reference",
"url": "https://doi.org/10.7312/pric91844"
}
},
"LAW-006": {
"id": "LAW-006",
"type": "law",
"file_path": "software-engineering/teams/putts-law.md",
"title": "Putts Law",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-007"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Hiring managers with technical backgrounds improves technical decision-making",
"Technical leadership roles (architect, tech lead) bridge the gap between management and expertise",
"Organizations should establish dual-track career paths for technical and managerial advancement",
"Decision-making structures should incorporate technical experts in management discussions"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Putt's Law and the Successful Technocrat",
"authors": [
"Archibald Putt"
],
"year": 1981,
"publisher": "John Wiley & Sons",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Putt%27s_Law"
}
},
"LAW-007": {
"id": "LAW-007",
"type": "law",
"file_path": "software-engineering/teams/peter-principle.md",
"title": "Peter Principle",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Promotion decisions should explicitly evaluate readiness for new roles",
"Training and support programs should help people transition between role types",
"Organizations should recognize different types of expertise and contribution",
"Lateral moves and skill development matter as much as vertical advancement"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Peter Principle",
"authors": [
"Laurence J. Peter",
"Raymond Hull"
],
"year": 1969,
"publisher": "William Morrow and Company",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Peter_principle"
}
},
"LAW-008": {
"id": "LAW-008",
"type": "law",
"file_path": "software-engineering/teams/bus-factor.md",
"title": "Bus Factor",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Documentation and runbooks reduce organizational risk",
"Mentorship and knowledge transfer programs improve team resilience",
"On-call and incident response systems should distribute responsibility",
"Organizations should actively increase bus factor through knowledge sharing",
"Code ownership models should avoid single ownership of critical systems"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Truck Number: A Metric for Software Projects",
"authors": [
"Brian W. Fitzpatrick"
],
"year": 2010,
"publisher": "Google Tech Talk / ApacheCON",
"license": "reference",
"note": "Popularized by the phrase 'lottery factor' and 'bus factor' in open-source communities",
"url": "https://en.wikipedia.org/wiki/Bus_factor"
}
},
"LAW-009": {
"id": "LAW-009",
"type": "law",
"file_path": "software-engineering/teams/dilbert-principle.md",
"title": "Dilbert Principle",
"category": "teams",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Organizations should resist using management as a dumping ground for difficult employees",
"Performance management systems should assess both technical and interpersonal contributions",
"Promotion criteria should explicitly evaluate management readiness and people skills",
"Alternative career paths prevent forced promotion of people unsuited to management"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Dilbert Principle",
"authors": [
"Scott Adams"
],
"year": 1996,
"publisher": "HarperBusiness",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Dilbert_principle"
}
},
"LAW-010": {
"id": "LAW-010",
"type": "law",
"file_path": "software-engineering/planning/premature-optimization.md",
"title": "Premature Optimization",
"category": "planning",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Performance budgets and monitoring guide optimization priorities",
"Development should prioritize clarity and correctness before optimization",
"Code reviews should question optimization that lacks performance profiling evidence",
"Profiling tools should be standard in development workflow",
"Late-stage optimization during load testing is preferable to early guessing"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Structured Programming with go to Statements",
"authors": [
"Donald E. Knuth"
],
"year": 1974,
"publisher": "ACM Computing Surveys, 6(4), 261-301",
"license": "reference",
"url": "https://doi.org/10.1145/356635.356640"
}
},
"LAW-011": {
"id": "LAW-011",
"type": "law",
"file_path": "software-engineering/planning/parkinsons-law.md",
"title": "Parkinsons Law",
"category": "planning",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Agile practices using time-boxed iterations leverage Parkinson's Law positively",
"Distinguishing between necessary slack and wasted time is important",
"Shorter sprint cycles encourage focused work and fast feedback",
"Clear deadlines prevent scope expansion and gold-plating",
"Resource allocation should account for this tendency"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Parkinson's Law",
"authors": [
"C. Northcote Parkinson"
],
"year": 1955,
"publisher": "The Economist",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Parkinson%27s_law"
}
},
"LAW-012": {
"id": "LAW-012",
"type": "law",
"file_path": "software-engineering/planning/ninety-ninety-rule.md",
"title": "Ninety Ninety Rule",
"category": "planning",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Time-boxed development with early testing reduces final-phase surprises",
"Definition of done should be clear and realistic upfront",
"Buffer estimates should be proportional to the type of project",
"Testing and quality assurance should begin earlier, not be deferred",
"Project estimates should account for the final 10% expansion explicitly"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Programming Pearls, 2nd Edition",
"authors": [
"Jon Bentley"
],
"year": 1986,
"publisher": "Addison-Wesley",
"license": "reference",
"note": "Attributed to Tom Cargill of Bell Labs",
"url": "https://en.wikipedia.org/wiki/Ninety-ninety_rule"
}
},
"LAW-013": {
"id": "LAW-013",
"type": "law",
"file_path": "software-engineering/planning/hofstadters-law.md",
"title": "Hofstadters Law",
"category": "planning",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-012"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Track estimation accuracy and adjust planning accordingly",
"Establish empirical velocity metrics from historical data rather than individual estimates",
"Break tasks into smaller increments to reduce estimation error",
"Multiply estimates by factors beyond simple buffers; add contingency for unknowns",
"Use ranges and confidence levels rather than point estimates"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Gödel, Escher, Bach: An Eternal Golden Braid",
"authors": [
"Douglas R. Hofstadter"
],
"year": 1979,
"publisher": "Basic Books",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Hofstadter%27s_law"
}
},
"LAW-014": {
"id": "LAW-014",
"type": "law",
"file_path": "software-engineering/planning/goodharts-law.md",
"title": "Goodharts Law",
"category": "planning",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Monitor for gaming behavior when metrics become targets",
"Establish balanced scorecards with multiple perspectives",
"Distinguish between metrics for measurement versus management",
"Avoid using single metrics for performance evaluation",
"Focus on outcomes rather than metrics-based incentives"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Problems of Monetary Management: The UK Experience",
"authors": [
"Charles A.E. Goodhart"
],
"year": 1975,
"publisher": "Reserve Bank of Australia",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Goodhart%27s_law"
}
},
"LAW-015": {
"id": "LAW-015",
"type": "law",
"file_path": "software-engineering/planning/gilbs-law.md",
"title": "Gilbs Law",
"category": "planning",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Establish baselines for improvement rather than exact truth",
"Start with imperfect metrics rather than delaying for perfect ones",
"Focus on trends and comparisons rather than absolute accuracy",
"Use metrics to identify problems even if they're not perfectly precise",
"Refine measurements over time as understanding improves"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Software Metrics",
"authors": [
"Tom Gilb"
],
"year": 1977,
"publisher": "Winthrop Publishers",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Gilb%27s_law"
}
},
"LAW-016": {
"id": "LAW-016",
"type": "law",
"file_path": "software-engineering/architecture/hyrums-law.md",
"title": "Hyrums Law",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-043"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Version management and deprecation processes are necessary for sustainability",
"Documentation should clarify what's guaranteed versus implementation detail",
"Internal implementation details should be hidden behind well-defined interfaces",
"API design should be intentional about what's observable and documented",
"Testing should verify contract compliance, not just functionality"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Hyrum's Law",
"authors": [
"Hyrum Wright"
],
"license": "reference",
"url": "https://www.hyrumslaw.com/"
}
},
"LAW-017": {
"id": "LAW-017",
"type": "law",
"file_path": "software-engineering/architecture/galls-law.md",
"title": "Galls Law",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Design should emerge from requirements of working systems",
"Incremental improvements to production systems beat complete redesigns",
"Microservices should evolve from monoliths; not the reverse",
"Start with working systems before adding complexity",
"Favor evolutionary architecture over big-bang redesigns"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Systemantics: How Systems Work and Especially How They Fail",
"authors": [
"John Gall"
],
"year": 1975,
"publisher": "Quadrangle",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/John_Gall_(author)#Gall%27s_law"
}
},
"LAW-018": {
"id": "LAW-018",
"type": "law",
"file_path": "software-engineering/architecture/law-of-leaky-abstractions.md",
"title": "Law Of Leaky Abstractions",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Performance-critical systems require understanding implementation",
"Provide \"escape hatches\" for cases where abstraction breaks",
"Test abstractions against edge cases where leaks appear",
"Document abstraction limitations and when implementation details matter",
"Design abstractions acknowledging where they leak"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Law of Leaky Abstractions",
"authors": [
"Joel Spolsky"
],
"year": 2002,
"license": "reference",
"url": "https://www.joelonsoftware.com/2002/11/11/the-law-of-leaky-abstractions/"
}
},
"LAW-019": {
"id": "LAW-019",
"type": "law",
"file_path": "software-engineering/architecture/teslers-law.md",
"title": "Teslers Law",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Low-code platforms shift complexity from developers to configuration",
"Configuration flexibility comes at the cost of user complexity",
"Simplifying interfaces requires robust hidden systems",
"User-friendly tools often require sophisticated backend systems",
"Design decisions should explicitly choose complexity location"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Tesler's Law (Law of Conservation of Complexity)",
"authors": [
"Larry Tesler"
],
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Law_of_conservation_of_complexity"
}
},
"LAW-020": {
"id": "LAW-020",
"type": "law",
"file_path": "software-engineering/architecture/cap-theorem.md",
"title": "Cap Theorem",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Design decisions must align system guarantees with application requirements",
"Eventual consistency is often acceptable for specific use cases",
"Monitoring and alerting become critical for partition scenarios",
"AP (Available, Partition-tolerant) systems: caches and read-heavy systems accepting eventual consistency",
"CP (Consistent, Partition-tolerant) systems: databases prioritizing data accuracy"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Towards robust distributed systems",
"authors": [
"Eric Brewer"
],
"year": 2000,
"publisher": "ACM Symposium on Principles of Distributed Computing (PODC)",
"license": "reference",
"url": "https://doi.org/10.1145/343477.343502"
}
},
"LAW-021": {
"id": "LAW-021",
"type": "law",
"file_path": "software-engineering/architecture/second-system-effect.md",
"title": "Second System Effect",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-023"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Team composition matters; fresh perspectives help combat the effect",
"Rewrite decisions should be cautious and deliberate",
"Incremental evolution might be preferable to complete replacement",
"Maintaining the first system's simplicity is an explicit goal for seconds",
"Feature lists for replacements should be conservative"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Mythical Man-Month",
"authors": [
"Frederick P. Brooks Jr."
],
"year": 1975,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Second-system_effect"
}
},
"LAW-022": {
"id": "LAW-022",
"type": "law",
"file_path": "software-engineering/architecture/fallacies-of-distributed-computing.md",
"title": "Fallacies Of Distributed Computing",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Measure and account for latency; design for acceptable performance within constraints",
"Design distributed systems assuming networks fail; implement retry and timeout logic",
"Build systems tolerant of topology changes",
"Implement security at every level; assume network compromise",
"Optimize data transfer; avoid unnecessary round trips"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Eight Fallacies of Distributed Computing",
"authors": [
"L. Peter Deutsch",
"James Gosling"
],
"year": 1994,
"publisher": "Sun Microsystems",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Fallacies_of_distributed_computing"
}
},
"LAW-023": {
"id": "LAW-023",
"type": "law",
"file_path": "software-engineering/architecture/law-of-unintended-consequences.md",
"title": "Law Of Unintended Consequences",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-036"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Monitoring and observability are essential for detecting unintended effects",
"Change management processes should anticipate and watch for surprises",
"Testing should focus on integration and system-level behavior, not just units",
"Documentation should capture system interdependencies and potential interactions",
"Large changes should be implemented incrementally with careful monitoring"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Unanticipated Consequences of Purposive Social Action",
"authors": [
"Robert K. Merton"
],
"year": 1936,
"publisher": "American Sociological Review, 1(6), 894-904",
"license": "reference",
"url": "https://doi.org/10.2307/2084615"
}
},
"LAW-024": {
"id": "LAW-024",
"type": "law",
"file_path": "software-engineering/architecture/zawinskis-law.md",
"title": "Zawinskis Law",
"category": "architecture",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Monitor feature expansion for architectural strain",
"Feature requests should be evaluated for long-term architectural impact",
"Architecture should accommodate feature expansion while maintaining clarity",
"Modular design enables expansion without complete redesign",
"Define and defend core scope to resist uncontrolled expansion"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Zawinski's Law",
"authors": [
"Jamie Zawinski"
],
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Jamie_Zawinski#Zawinski's_law"
}
},
"LAW-025": {
"id": "LAW-025",
"type": "law",
"file_path": "software-engineering/quality/boy-scout-rule.md",
"title": "Boy Scout Rule",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-028",
"LAW-029"
],
"violates": [],
"related_to": [
"LAW-029"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Code reviews should encourage Boy Scout improvements",
"Developers should allocate time during feature work for small refactoring",
"Establish refactoring guidelines: variable renames, extract methods, remove duplication",
"Measure code quality trends to track the effect of Boy Scout practices",
"Resist the trap of \"we'll refactor later\"; refactor as you go"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Clean Code",
"authors": [
"Robert C. Martin"
],
"year": 2008,
"publisher": "Prentice Hall",
"license": "reference",
"url": "https://www.oreilly.com/library/view/clean-code-a/9780136083238/"
}
},
"LAW-026": {
"id": "LAW-026",
"type": "law",
"file_path": "software-engineering/quality/murphys-law.md",
"title": "Murphys Law",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Use fault injection and chaos engineering to find problems before production",
"Implement monitoring and alerting for potential failures",
"Design for failure: implement timeouts, retries, and fallbacks",
"Test edge cases and boundary conditions thoroughly",
"Validate inputs; don't assume data is well-formed"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Murphy's Law and Other Reasons Why Things Go Wrong",
"authors": [
"Arthur Bloch"
],
"year": 1977,
"publisher": "Price/Stern/Sloan",
"license": "reference",
"note": "Origin popularized in U.S. aerospace engineering (Edwards AFB, 1949)",
"url": "https://en.wikipedia.org/wiki/Murphy%27s_law"
}
},
"LAW-027": {
"id": "LAW-027",
"type": "law",
"file_path": "software-engineering/quality/postels-law.md",
"title": "Postels Law",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Error handling should be forgiving when possible while logging issues",
"Libraries should accept multiple formats and versions of inputs",
"Data parsers should handle variations gracefully without failing",
"API design should be strict about response format but lenient about request parsing",
"Deprecated API versions should be supported for extended periods"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "RFC 793: Transmission Control Protocol (TCP)",
"authors": [
"Jon Postel"
],
"year": 1981,
"publisher": "Internet Engineering Task Force (IETF)",
"license": "reference",
"url": "https://doi.org/10.17487/RFC0793"
}
},
"LAW-028": {
"id": "LAW-028",
"type": "law",
"file_path": "software-engineering/quality/broken-windows-theory.md",
"title": "Broken Windows Theory",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-023",
"LAW-025",
"LAW-029"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Refactoring should be regular, not deferred",
"Tools and automation should enforce quality standards",
"Team culture should emphasize quality standards",
"Technical debt should be explicitly tracked and addressed",
"Code reviews should catch and address quality issues promptly"
],
"when_not_to_use": [],
"symptoms": [
"Law violation indicators present"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Broken Windows: The Police and Neighborhood Safety",
"authors": [
"James Q. Wilson",
"George L. Kelling"
],
"year": 1982,
"publisher": "The Atlantic Monthly",
"license": "reference",
"url": "https://doi.org/10.1177/0032258X8307400305"
}
},
"LAW-029": {
"id": "LAW-029",
"type": "law",
"file_path": "software-engineering/quality/technical-debt.md",
"title": "Technical Debt",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-025",
"LAW-028",
"LAW-034"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Distinguish between debt incurred intentionally and debt from mistakes",
"Track technical debt explicitly; don't ignore it",
"Refactoring and modernization efforts address debt strategically",
"Allocate time for paying down debt; don't defer indefinitely",
"Understand that some technical debt is strategic and acceptable"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "TechnicalDebt",
"authors": [
"Martin Fowler"
],
"license": "reference",
"url": "https://martinfowler.com/bliki/TechnicalDebt.html"
}
},
"LAW-030": {
"id": "LAW-030",
"type": "law",
"file_path": "software-engineering/quality/linuss-law.md",
"title": "Linuss Law",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-031",
"LAW-033"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Implement mandatory code review processes",
"Documentation and clarity enable more effective review",
"Encourage open-source contributions to expose code to broader scrutiny",
"Involve multiple reviewers for critical code",
"Diverse teams catch more bugs than homogeneous teams"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Cathedral and the Bazaar",
"authors": [
"Eric S. Raymond"
],
"year": 1999,
"publisher": "O'Reilly Media",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Linus%27s_law"
}
},
"LAW-031": {
"id": "LAW-031",
"type": "law",
"file_path": "software-engineering/quality/kernighans-law.md",
"title": "Kernighans Law",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Add helpful comments explaining non-obvious logic",
"Write code for clarity, not cleverness",
"Implement logging and observability for debugging",
"Avoid overly complex algorithms when simpler alternatives suffice",
"Use meaningful variable and function names"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Elements of Programming Style",
"authors": [
"Brian Kernighan",
"P.J. Plauger"
],
"year": 1974,
"publisher": "McGraw-Hill",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Kernighan%27s_law"
}
},
"LAW-032": {
"id": "LAW-032",
"type": "law",
"file_path": "software-engineering/quality/testing-pyramid.md",
"title": "Testing Pyramid",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-030",
"LAW-033"
],
"violates": [],
"related_to": [
"LAW-030",
"LAW-033"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"End-to-end tests should cover critical user paths",
"Organize tests by level: unit, integration, end-to-end",
"Maintain fast unit test execution (under a few seconds)",
"Integration tests should verify boundaries between components",
"Use mocks and stubs to isolate unit tests"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Succeeding with Agile: Software Development Using Scrum",
"authors": [
"Mike Cohn"
],
"year": 2009,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Testing_pyramid"
}
},
"LAW-033": {
"id": "LAW-033",
"type": "law",
"file_path": "software-engineering/quality/pesticide-paradox.md",
"title": "Pesticide Paradox",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-030",
"LAW-032"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Refactor tests alongside code refactoring",
"Test coverage should increase as the codebase grows",
"Ensure new features have test coverage",
"Review and update test cases regularly",
"Add new tests when bugs are found to prevent regression"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Software Testing Techniques, 2nd Edition",
"authors": [
"Boris Beizer"
],
"year": 1990,
"publisher": "Van Nostrand Reinhold",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Pesticide_paradox"
}
},
"LAW-034": {
"id": "LAW-034",
"type": "law",
"file_path": "software-engineering/quality/lehmans-laws.md",
"title": "Lehmans Laws",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Budget for maintenance; evolution requires increasing effort",
"Maintain architecture; unstructured evolution increases complexity unacceptably",
"Plan for continuous evolution; systems are never \"done\"",
"Invest in quality; systems degrade without active attention",
"Monitor development velocity; overloaded systems stabilize at lower velocity"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Laws of Software Evolution Revisited",
"authors": [
"Meir M. Lehman"
],
"year": 1996,
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Lehman%27s_laws_of_software_evolution"
}
},
"LAW-035": {
"id": "LAW-035",
"type": "law",
"file_path": "software-engineering/quality/sturgeons-law.md",
"title": "Sturgeons Law",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Carefully evaluate libraries and frameworks; most are mediocre",
"Study good code; learn from the best 10%",
"Invest in quality tools and platforms; the best outweigh the cost",
"Develop good taste in code quality and design",
"Recognize that creating good software requires more than average effort"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "On 'The Science Fiction Dimension' (Venture Science Fiction)",
"authors": [
"Theodore Sturgeon"
],
"year": 1953,
"publisher": "Venture Science Fiction Magazine",
"license": "reference",
"note": "Sturgeon's revelation: 'ninety percent of everything is crap'",
"url": "https://en.wikipedia.org/wiki/Sturgeon%27s_law"
}
},
"LAW-036": {
"id": "LAW-036",
"type": "law",
"file_path": "software-engineering/quality/yagni.md",
"title": "Yagni",
"category": "quality",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-041"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Refactor when actual requirements emerge, not speculatively",
"When adding a feature seems tempting, ask: \"Will we actually use it?\"",
"Resist the temptation to over-engineer for flexibility",
"Keep codebases simple; add complexity only when necessary",
"Focus development on current requirements, not anticipated future needs"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Extreme Programming Explained: Embrace Change",
"authors": [
"Kent Beck"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it"
}
},
"LAW-037": {
"id": "LAW-037",
"type": "law",
"file_path": "software-engineering/scalability/amdahls-law.md",
"title": "Amdahls Law",
"category": "scalability",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-038"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Understand that complete parallelization is impossible in real systems",
"Identify serial bottlenecks before parallelizing",
"Focus optimization efforts on high-parallelization-potential code",
"Use Amdahl's Law to calculate maximum achievable speedup",
"Consider whether parallelization effort justifies expected speedup"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Validity of the Single Processor Approach to Achieving Large-Scale Computing Capabilities",
"authors": [
"Gene Amdahl"
],
"year": 1967,
"publisher": "AFIPS Conference Proceedings",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Amdahl%27s_law"
}
},
"LAW-038": {
"id": "LAW-038",
"type": "law",
"file_path": "software-engineering/scalability/gustafsons-law.md",
"title": "Gustafsons Law",
"category": "scalability",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Cloud computing enables scaling problem size with parallelization",
"Distributed systems handle larger data and workload scales through parallelization",
"High-performance computing uses Gustafson's Law to justify massive parallelization",
"Consider growth and scaling when designing parallelizable systems",
"Scale problem size with available resources for better parallelization"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Reevaluating Amdahl's Law",
"authors": [
"John L. Gustafson"
],
"year": 1988,
"publisher": "Communications of the ACM",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Gustafson%27s_law"
}
},
"LAW-039": {
"id": "LAW-039",
"type": "law",
"file_path": "software-engineering/scalability/metcalfes-law.md",
"title": "Metcalfes Law",
"category": "scalability",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Switching costs and platform lock-in create competitive advantages",
"Network effects drive platform strategy and growth prioritization",
"Early-stage networks suffer from low value; critical mass is essential",
"Understand when products benefit from network effects versus when they don't",
"Platforms should prioritize growth to reach critical mass faster"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Metcalfe's Law",
"authors": [
"Robert Metcalfe"
],
"year": 1980,
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Metcalfe%27s_law"
}
},
"LAW-040": {
"id": "LAW-040",
"type": "law",
"file_path": "software-engineering/design/dry.md",
"title": "Dry",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Constants and magic numbers should be defined once",
"Use database normalization to eliminate data duplication",
"Configuration should not be duplicated across files",
"Extract common code into functions and modules",
"Documentation should reference a single source of truth"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Pragmatic Programmer",
"authors": [
"Andrew Hunt",
"David Thomas"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/"
}
},
"LAW-041": {
"id": "LAW-041",
"type": "law",
"file_path": "software-engineering/design/kiss.md",
"title": "Kiss",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-043"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Remove unnecessary features and code",
"Favor straightforward algorithms and approaches",
"Refactor for simplicity, not just functionality",
"Question complexity; ensure it addresses real needs",
"Avoid premature generalization and over-engineering"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "KISS Principle",
"authors": [
"Clarence 'Kelly' Johnson"
],
"year": 1960,
"publisher": "U.S. Navy / Lockheed Skunk Works",
"license": "reference",
"note": "Design principle originated by Kelly Johnson at Lockheed",
"url": "https://en.wikipedia.org/wiki/KISS_principle"
}
},
"LAW-042": {
"id": "LAW-042",
"type": "law",
"file_path": "software-engineering/design/solid-principles.md",
"title": "Solid Principles",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-040",
"LAW-041",
"LAW-043"
],
"violates": [],
"related_to": [
"LAW-040"
],
"requires": [],
"enables": [],
"violated_by": []
},
"context": {
"when_to_use": [
"Keep interfaces focused; don't force clients to depend on unused methods",
"Use inheritance and composition to extend systems without modification",
"Verify that derived classes can substitute for base classes",
"Design classes with single, well-defined responsibilities",
"Use dependency injection to depend on abstractions"
],
"when_not_to_use": [],
"symptoms": [
"Law violation indicators present"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Agile Software Development: Principles, Patterns, and Practices",
"authors": [
"Robert C. Martin"
],
"year": 2002,
"publisher": "Prentice Hall",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/SOLID"
}
},
"LAW-043": {
"id": "LAW-043",
"type": "law",
"file_path": "software-engineering/design/law-of-demeter.md",
"title": "Law Of Demeter",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-040",
"LAW-041"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Service layers decouple layers from internal details",
"Aggregator objects gather necessary dependencies",
"Dependency injection provides immediate dependencies",
"Avoid chaining method calls across multiple objects (a.b.c.d)",
"Use facade objects to hide complex internal structures"
],
"when_not_to_use": [],
"symptoms": [
"Law violation indicators present"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Law of Demeter",
"authors": [
"Karl Lieberherr",
"Ian Holland"
],
"year": 1987,
"publisher": "OOPSLA",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Law_of_Demeter"
}
},
"LAW-044": {
"id": "LAW-044",
"type": "law",
"file_path": "software-engineering/design/principle-of-least-astonishment.md",
"title": "Principle Of Least Astonishment",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-042"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"System defaults should match user expectations",
"Configuration behavior should follow intuitive patterns",
"Error messages should be clear and expected",
"Consistent naming and patterns reduce confusion",
"API design should follow conventions developers expect"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Art of UNIX Programming",
"authors": [
"Eric S. Raymond"
],
"year": 2003,
"publisher": "Addison-Wesley",
"license": "reference",
"note": "POLA concept originated in MIT AI Lab culture (1970s-80s)",
"url": "https://en.wikipedia.org/wiki/Principle_of_least_astonishment"
}
},
"LAW-045": {
"id": "LAW-045",
"type": "law",
"file_path": "software-engineering/decisions/dunning-kruger-effect.md",
"title": "Dunning Kruger Effect",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Involve experienced people in architecture decisions; don't rely on confident novices",
"Be cautious of high-confidence estimates from those new to a domain",
"Training reduces overconfidence by exposing gaps",
"Code reviews catch overconfident decisions",
"Seek expert opinions; experts express appropriate uncertainty"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Unskilled and Unaware of It: How Difficulties in Recognizing One's Own Incompetence Lead to Inflated Self-Assessments",
"authors": [
"Justin Kruger",
"David Dunning"
],
"year": 1999,
"publisher": "Journal of Personality and Social Psychology, 77(6), 1121-1134",
"license": "reference",
"url": "https://doi.org/10.1037/0022-3514.77.6.1121"
}
},
"LAW-046": {
"id": "LAW-046",
"type": "law",
"file_path": "software-engineering/decisions/hanlons-razor.md",
"title": "Hanlons Razor",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Create psychologically safe environments where mistakes are acknowledged",
"Investigate root causes of failures rather than assigning blame",
"Assume good intent in code reviews and team interactions",
"Focus on systems and processes preventing mistakes, not blaming individuals",
"Improve systems and training rather than firing people for mistakes"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Hanlon's Razor",
"authors": [
"Robert J. Hanlon"
],
"year": 1980,
"publisher": "Submitted to a joke book compiled by Arthur Bloch",
"license": "reference",
"note": "Phrase: 'Never attribute to malice that which is adequately explained by stupidity'",
"url": "https://en.wikipedia.org/wiki/Hanlon%27s_razor"
}
},
"LAW-047": {
"id": "LAW-047",
"type": "law",
"file_path": "software-engineering/decisions/occams-razor.md",
"title": "Occams Razor",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-036",
"LAW-041"
],
"violates": [],
"related_to": [
"LAW-046"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Question elaborate theories; seek simpler explanations",
"Design systems simply; add complexity only when necessary",
"Choose simple solutions unless evidence demands complexity",
"YAGNI and KISS principles apply Occam's Razor",
"Debug assuming simple causes before investigating exotic ones"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Occam's Razor (Lex Parsimoniae)",
"authors": [
"William of Ockham"
],
"year": 1323,
"publisher": "Medieval philosophical tradition",
"license": "reference",
"note": "Attributed to William of Ockham (c. 1287-1347)",
"url": "https://en.wikipedia.org/wiki/Occam%27s_razor"
}
},
"LAW-048": {
"id": "LAW-048",
"type": "law",
"file_path": "software-engineering/decisions/sunk-cost-fallacy.md",
"title": "Sunk Cost Fallacy",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Career decisions should consider future fit, not career investment",
"Evaluate technology and approach decisions based on current fit, not past investment",
"Rewrite decisions should compare future value, not past effort",
"Have explicit criteria for abandoning projects despite sunk costs",
"Create environments where admitting mistakes is safe"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Sunk Cost Fallacy",
"authors": [
"Richard Thaler"
],
"year": 1980,
"publisher": "Behavioral economics literature",
"license": "reference",
"note": "Key concept in behavioral economics; Thaler (1980) 'Toward a Positive Theory of Consumer Choice'",
"url": "https://en.wikipedia.org/wiki/Sunk_cost#Fallacy_effect"
}
},
"LAW-049": {
"id": "LAW-049",
"type": "law",
"file_path": "software-engineering/decisions/map-is-not-territory.md",
"title": "Map Is Not Territory",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Validate assumptions about user behavior empirically",
"Recognize that requirements documents don't capture all complexity",
"Design for uncertainty; expect reality to deviate from models",
"Models and simulations guide but don't guarantee outcomes",
"Architecture diagrams simplify reality; systems are more complex"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Science and Sanity: An Introduction to Non-Aristotelian Systems and General Semantics",
"authors": [
"Alfred Korzybski"
],
"year": 1933,
"publisher": "International Non-Aristotelian Library",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Map%E2%80%93territory_relation"
}
},
"LAW-050": {
"id": "LAW-050",
"type": "law",
"file_path": "software-engineering/decisions/confirmation-bias.md",
"title": "Confirmation Bias",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Devil's advocate role in design decisions surfaces contradictions",
"Use metrics and data to overcome intuition-based bias",
"Actively seek disconfirming evidence; challenge assumptions",
"Implement code review processes to catch biased decisions",
"Pre-mortems imagine failure and challenge assumptions"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "On the Failure to Eliminate Hypotheses in a Conceptual Task",
"authors": [
"Peter C. Wason"
],
"year": 1960,
"publisher": "Quarterly Journal of Experimental Psychology, 12(3), 129-140",
"license": "reference",
"url": "https://doi.org/10.1080/17470216008416717"
}
},
"LAW-051": {
"id": "LAW-051",
"type": "law",
"file_path": "software-engineering/decisions/hype-cycle-and-amaras-law.md",
"title": "Hype Cycle And Amaras Law",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Evaluate technologies for actual fit, not hype",
"Early adopters gain advantage if technology survives hype cycle",
"Avoid adopting every new technology at peak hype",
"Plan for disillusionment; long-term benefits matter",
"Mature technologies are safer but may be aging out"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Hype Cycle / Amara's Law",
"authors": [
"Roy Amara",
"Jackie Fenn (Gartner)"
],
"year": 1995,
"publisher": "Gartner",
"license": "reference",
"note": "Amara: 'We overestimate the effect of a technology in the short run and underestimate the effect in the long run.' Gartner Hype Cycle formalized by Fenn (1995)",
"url": "https://en.wikipedia.org/wiki/Hype_cycle"
}
},
"LAW-052": {
"id": "LAW-052",
"type": "law",
"file_path": "software-engineering/decisions/lindy-effect.md",
"title": "Lindy Effect",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Ideas surviving decades are likely valuable long-term",
"Evaluate technology maturity; maturity indicates future viability",
"Prefer established technologies over new ones unless clear benefits exist",
"Risk new technologies appropriately; they may not survive",
"Long-lived programming languages (C, Lisp, Python) are safe bets"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "The Fractal Geometry of Nature",
"authors": [
"Benoit B. Mandelbrot"
],
"year": 1982,
"publisher": "W.H. Freeman",
"license": "reference",
"note": "Named after Lindy's deli in NYC; popularized by Nassim Nicholas Taleb in 'Antifragile' (2012)",
"url": "https://en.wikipedia.org/wiki/Lindy_effect"
}
},
"LAW-053": {
"id": "LAW-053",
"type": "law",
"file_path": "software-engineering/decisions/first-principles-thinking.md",
"title": "First Principles Thinking",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-036",
"LAW-047"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"When solving novel problems, break them into fundamental components",
"Design thinking and user research reveal fundamental needs",
"Root cause analysis investigates first principles of problems",
"Innovation often comes from reconsidering fundamentals",
"Challenge \"that's how we've always done it\" with first principles"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "First Principles Thinking",
"authors": [
"Aristotle"
],
"year": -350,
"publisher": "Aristotelian philosophical tradition (Physics, Metaphysics)",
"license": "reference",
"note": "Ancient Greek philosophical method; revived by Elon Musk and others in modern engineering",
"url": "https://en.wikipedia.org/wiki/First_principle"
}
},
"LAW-054": {
"id": "LAW-054",
"type": "law",
"file_path": "software-engineering/decisions/inversion.md",
"title": "Inversion",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Risk analysis inverts goals: what would cause project failure?",
"Security analysis inverts goals: how would systems be breached?",
"Architecture decisions consider what would break systems",
"Design reviews identify what makes designs fail",
"Pre-mortems imagine project failure; prevent identified causes"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Inversion (Invert, always invert)",
"authors": [
"Carl Gustav Jacob Jacobi"
],
"year": 1830,
"publisher": "Mathematical tradition",
"license": "reference",
"note": "Jacobi's motto: 'Invert, always invert.' Popularized in investing by Charlie Munger",
"url": "https://en.wikipedia.org/wiki/Inverse_(mathematics)"
}
},
"LAW-055": {
"id": "LAW-055",
"type": "law",
"file_path": "software-engineering/decisions/pareto-principle.md",
"title": "Pareto Principle",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Technical debt: focus on code causing 80% of maintenance burden",
"Performance: optimize code responsible for 80% of latency",
"Feature development: 20% of features provide 80% of value",
"Bug fixes: focus on code causing 80% of defects",
"Customer issues: 20% of issues cause 80% of customer complaints"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Cours d'économie politique",
"authors": [
"Vilfredo Pareto"
],
"year": 1896,
"publisher": "Lausanne",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/Pareto_principle"
}
},
"LAW-056": {
"id": "LAW-056",
"type": "law",
"file_path": "software-engineering/decisions/cunninghams-law.md",
"title": "Cunninghams Law",
"category": "decisions",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Frame statements as proposals to invite correction and improvement",
"Propose solutions, even uncertain ones, to elicit expert feedback",
"Use code review as learning opportunity; make proposals and learn from feedback",
"Post uncertain findings for community correction rather than asking open questions",
"Create mistakes in code reviews to surface expert knowledge"
],
"when_not_to_use": [],
"symptoms": [],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Cunningham's Law",
"authors": [
"Ward Cunningham"
],
"year": 2004,
"publisher": "Wiki culture / Cunningham & Cunningham, Inc.",
"license": "reference",
"note": "'The best way to get the right answer on the Internet is not to ask a question, it's to post the wrong answer.'",
"url": "https://en.wikipedia.org/wiki/Ward_Cunningham"
}
},
"RF-006": {
"id": "RF-006",
"type": "refactoring",
"file_path": "refactoring/composing-methods/replace-method-with-method-object.md",
"title": "Replace Method With Method Object",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-041",
"LAW-042-S"
],
"violates": [],
"related_to": [
"LAW-042-D",
"RF-001",
"RF-010"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method is too long and uses many local variables that prevent Extract Method",
"Local variable dependencies make it impossible to break a method into smaller pieces",
"You need to isolate a complex algorithm into its own object for testability"
],
"when_not_to_use": [],
"symptoms": [
"Methods with many local variables that prevent straightforward extraction",
"Long methods where Extract Method fails due to tangled variable usage"
],
"benefits": [
"Allows decomposition of very long methods that resist normal Extract Method",
"Enables step-by-step transformation of procedural code into object-oriented structure",
"Makes the algorithm independently testable in isolation"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-007": {
"id": "RF-007",
"type": "refactoring",
"file_path": "refactoring/composing-methods/replace-temp-with-query.md",
"title": "Replace Temp With Query",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-040",
"LAW-041"
],
"violates": [],
"related_to": [
"RF-001",
"RF-005"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A temporary variable is assigned more than once and serves multiple unrelated purposes",
"A loop variable accumulates different kinds of values within the same scope",
"Reuse of a temp variable makes the code harder to follow"
],
"when_not_to_use": [],
"symptoms": [
"Temporary variables that are reassigned multiple times for different purposes",
"Variables named generically (temp, val, x) because they serve multiple roles"
],
"benefits": [
"Each variable has a single, clear responsibility with a descriptive name",
"Eliminates confusion caused by variables that change meaning mid-method",
"Makes the code safe for Extract Method since variables are no longer reused"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-008": {
"id": "RF-008",
"type": "refactoring",
"file_path": "refactoring/composing-methods/split-temporary-variable.md",
"title": "Split Temporary Variable",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [
"SMELL-01",
"SMELL-13"
],
"enforces": [
"LAW-041",
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-004"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method assigns to its input parameters, making the calling code misleading",
"Assignments to parameters create confusion about whether the caller sees changes",
"You want to enforce the convention of treating parameters as read-only"
],
"when_not_to_use": [],
"symptoms": [
"Parameters that are reassigned within the method body",
"Code where it is unclear whether parameter mutation affects the caller"
],
"benefits": [
"Clarifies the distinction between input parameters and local computation values",
"Prevents subtle bugs from misunderstanding pass-by-value vs pass-by-reference semantics",
"Makes method behavior more predictable and easier to reason about"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-009": {
"id": "RF-009",
"type": "refactoring",
"file_path": "refactoring/composing-methods/substitute-algorithm.md",
"title": "Substitute Algorithm",
"category": "composing_methods",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-031",
"LAW-041"
],
"violates": [],
"related_to": [
"RF-001",
"RF-006",
"RF-003"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"You want to replace a complex algorithm with a simpler or more performant one",
"The current implementation is correct but overly convoluted",
"A library function or well-known algorithm can replace custom logic"
],
"when_not_to_use": [],
"symptoms": [
"An algorithm that works but is harder to understand than necessary",
"Custom implementations of algorithms that have standard library equivalents"
],
"benefits": [
"Dramatically simplifies code by swapping an entire algorithm at once",
"Can improve performance by replacing a naive algorithm with an optimized one",
"Reduces maintenance burden by using well-understood, tested algorithms"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-010": {
"id": "RF-010",
"type": "refactoring",
"file_path": "refactoring/moving-features/extract-class.md",
"title": "Extract Class",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [
"SMELL-04",
"SMELL-05",
"SMELL-08",
"SMELL-09",
"SMELL-10",
"SMELL-21"
],
"enforces": [
"LAW-040",
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-001",
"RF-056",
"RF-057",
"RF-058"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A class has grown too large and contains groups of methods that logically belong together",
"Some data and methods of a class could form a cohesive unit on their own",
"You want to apply Single Responsibility Principle by splitting a class"
],
"when_not_to_use": [],
"symptoms": [
"A class that handles multiple unrelated concerns or responsibilities",
"Subset of fields and methods that always change together but are independent of other subsets"
],
"benefits": [
"Creates focused, single-responsibility classes that are easier to understand and maintain",
"Reduces coupling by isolating related behavior into its own class",
"Makes each extracted class independently testable"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-011": {
"id": "RF-011",
"type": "refactoring",
"file_path": "refactoring/moving-features/hide-delegate.md",
"title": "Hide Delegate",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [
"SMELL-20"
],
"enforces": [
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-017",
"RF-023"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A client is calling methods on an object obtained through a delegate chain",
"You want to hide the internal structure of an object's associations",
"Changes to the delegate's interface should not propagate to callers"
],
"when_not_to_use": [],
"symptoms": [
"Call chains like order.customer.address.city in client code",
"Clients that know too much about the internal structure of collaborating objects"
],
"benefits": [
"Reduces coupling by hiding the chain of object interactions",
"Shields clients from changes in the delegated object's interface",
"Keeps the law of Demeter by avoiding chaining through multiple objects"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-012": {
"id": "RF-012",
"type": "refactoring",
"file_path": "refactoring/moving-features/inline-class.md",
"title": "Inline Class",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [
"SMELL-11",
"SMELL-12",
"SMELL-15"
],
"enforces": [
"LAW-041"
],
"violates": [],
"related_to": [
"RF-010",
"RF-017"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A class no longer carries its weight and its features belong in another class",
"After moving all features out, a class is effectively empty or trivial",
"A refactoring like Move Method has left a class with almost no behavior"
],
"when_not_to_use": [],
"symptoms": [
"A class that acts as a mere wrapper with no real behavior of its own",
"Files where almost every method just delegates to another object"
],
"benefits": [
"Eliminates unnecessary abstraction layers and reduces codebase complexity",
"Consolidates related logic into a single location",
"Removes indirection that makes the code harder to navigate"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-013": {
"id": "RF-013",
"type": "refactoring",
"file_path": "refactoring/moving-features/introduce-foreign-method.md",
"title": "Introduce Foreign Method",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [
"SMELL-18"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-014",
"RF-016"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"You need to add behavior to a library class but cannot modify its source",
"A utility method logically belongs to an external type but cannot be added there",
"You want to keep a domain-specific operation close to the type it operates on"
],
"when_not_to_use": [],
"symptoms": [
"Utility methods that take an external type as their first parameter",
"Repeated code that operates on a library class scattered across the codebase"
],
"benefits": [
"Extends external types without modifying their source code",
"Keeps utility operations discoverable near the type they enhance",
"Provides a stepping stone toward Introduce Local Extension"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-014": {
"id": "RF-014",
"type": "refactoring",
"file_path": "refactoring/moving-features/introduce-local-extension.md",
"title": "Introduce Local Extension",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-013"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"You need multiple additional methods on a library class you cannot modify",
"Introduce Foreign Method is insufficient because you need many additions",
"You want a cohesive API that extends a third-party type with domain operations"
],
"when_not_to_use": [],
"symptoms": [
"Many foreign methods scattered across helper classes for the same external type",
"Repeated wrapping logic or conversion code for a third-party library class"
],
"benefits": [
"Creates a unified extension of an external type with multiple methods",
"Keeps all extension methods together in a single, cohesive class",
"Allows the extension to maintain its own state and invariants"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-015": {
"id": "RF-015",
"type": "refactoring",
"file_path": "refactoring/moving-features/move-field.md",
"title": "Move Field",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [
"SMELL-09",
"SMELL-10",
"SMELL-15",
"SMELL-18",
"SMELL-19"
],
"enforces": [
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-016",
"RF-019"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A field is used more heavily by another class than by its owning class",
"Feature Envy is detected: a field is accessed mostly through foreign methods",
"Moving the field would reduce the need for cross-class field access"
],
"when_not_to_use": [],
"symptoms": [
"A field that is accessed primarily by another class through getters or setters",
"Feature Envy: methods in one class frequently access a field of another class"
],
"benefits": [
"Places data close to the behavior that uses it most",
"Reduces cross-class coupling and access patterns",
"Makes data ownership clearer and more logical"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-016": {
"id": "RF-016",
"type": "refactoring",
"file_path": "refactoring/moving-features/move-method.md",
"title": "Move Method",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [
"SMELL-04",
"SMELL-05",
"SMELL-09",
"SMELL-10",
"SMELL-15",
"SMELL-18",
"SMELL-19",
"SMELL-20",
"SMELL-21",
"SMELL-22"
],
"enforces": [
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-013",
"RF-015"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method is used more by another class than by its current owner",
"Feature Envy is detected: a method accesses more data from another class",
"A method clearly belongs conceptually to a different class"
],
"when_not_to_use": [],
"symptoms": [
"A method that calls more foreign class methods than its own class methods",
"Methods that seem misplaced in their current class from a domain perspective"
],
"benefits": [
"Reduces coupling by placing behavior near the data it operates on",
"Makes class responsibilities clearer and more cohesive",
"Often reveals hidden design concepts and opportunities for further refactoring"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-017": {
"id": "RF-017",
"type": "refactoring",
"file_path": "refactoring/moving-features/remove-middle-man.md",
"title": "Remove Middle Man",
"category": "moving_features",
"tags": [],
"relations": {
"solves": [
"SMELL-14"
],
"enforces": [
"LAW-041",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-011",
"RF-012"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A class has too many delegation methods that add no value",
"Clients can and should interact with the delegated object directly",
"The middle man class is a pass-through that obscures the real object"
],
"when_not_to_use": [],
"symptoms": [
"A class where most methods just delegate to another object with no added logic",
"Excessive use of Hide Delegate that creates an unnecessary wrapper layer"
],
"benefits": [
"Eliminates unnecessary delegation layers and reduces code volume",
"Gives clients direct access to the full API of the delegated object",
"Makes the code more transparent by removing trivial pass-through methods"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-018": {
"id": "RF-018",
"type": "refactoring",
"file_path": "refactoring/organizing-data/change-bidirectional-association-to-unidirectional.md",
"title": "Change Bidirectional Association To Unidirectional",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-19"
],
"enforces": [
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-015",
"RF-020"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A bidirectional association is no longer needed in both directions",
"One direction of navigation is never used in practice",
"You want to simplify the class and remove the complexity of maintaining two-way links"
],
"when_not_to_use": [],
"symptoms": [
"A back-reference pointer that is never actually traversed in the codebase",
"Difficult bugs arising from keeping both sides of a bidirectional link in sync"
],
"benefits": [
"Eliminates the complexity of keeping both sides of an association synchronized",
"Reduces coupling between the two classes",
"Simplifies the data model by removing unnecessary back-references"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-019": {
"id": "RF-019",
"type": "refactoring",
"file_path": "refactoring/organizing-data/change-reference-to-value.md",
"title": "Change Reference To Value",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-13"
],
"enforces": [
"LAW-040",
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-021"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"You have a reference object that should be treated as a simple value",
"Shared references are causing unintended aliasing bugs",
"Immutable value semantics are desired for comparison and hashing"
],
"when_not_to_use": [],
"symptoms": [
"Unexpected side effects when modifying an object shared through references",
"Complex equality logic needed because identity-based comparison is wrong for the domain"
],
"benefits": [
"Simplifies code by making copies that can be compared by value",
"Eliminates aliasing bugs where modifying one reference affects another",
"Enables safe use as dictionary keys or set members"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-020": {
"id": "RF-020",
"type": "refactoring",
"file_path": "refactoring/organizing-data/change-unidirectional-association-to-bidirectional.md",
"title": "Change Unidirectional Association To Bidirectional",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-19"
],
"enforces": [
"LAW-043"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Two objects need to navigate to each other and currently only one direction exists",
"You need to traverse the association from both sides efficiently",
"The domain model requires a genuine two-way relationship"
],
"when_not_to_use": [],
"symptoms": [
"Code performing expensive queries to traverse a relationship backwards",
"Domain concepts that are inherently bidirectional but modeled unidirectionally"
],
"benefits": [
"Enables efficient navigation in both directions without queries",
"Reflects a genuine bidirectional domain relationship in the code model",
"Improves performance by avoiding repeated lookups"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-021": {
"id": "RF-021",
"type": "refactoring",
"file_path": "refactoring/organizing-data/change-value-to-reference.md",
"title": "Change Value To Reference",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-07",
"SMELL-13"
],
"enforces": [
"LAW-040"
],
"violates": [],
"related_to": [
"RF-019",
"DP-011",
"RF-049"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Multiple copies of the same logical entity exist and should share identity",
"You need to ensure all references point to the same object instance",
"Updating one reference should be visible through all others"
],
"when_not_to_use": [],
"symptoms": [
"Multiple copies of the same logical entity that can drift out of sync",
"Equality checks based on data fields instead of identity for mutable objects"
],
"benefits": [
"Ensures all references to a logical entity point to the same object",
"Simplifies updates since changes propagate automatically through shared references",
"Reduces memory usage by eliminating duplicate copies of the same data"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-022": {
"id": "RF-022",
"type": "refactoring",
"file_path": "refactoring/organizing-data/duplicate-observed-data.md",
"title": "Duplicate Observed Data",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-13",
"SMELL-19"
],
"enforces": [
"LAW-040",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-015",
"RF-019"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Domain data in a GUI must be kept in sync with a separate presentation copy",
"You need to observe and propagate changes from domain objects to a UI layer",
"Observer pattern is needed but domain objects cannot directly reference UI code"
],
"when_not_to_use": [],
"symptoms": [
"Domain objects mixed with UI code that is difficult to test",
"Presentation state that diverges from domain state after updates"
],
"benefits": [
"Separates domain logic from UI rendering concerns",
"Ensures consistency between domain state and what is displayed",
"Enables multiple views to observe the same domain data independently"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-023": {
"id": "RF-023",
"type": "refactoring",
"file_path": "refactoring/organizing-data/encapsulate-collection.md",
"title": "Encapsulate Collection",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-20"
],
"enforces": [
"LAW-043"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A getter returns a direct reference to a mutable internal collection",
"Clients can bypass encapsulation by modifying the collection directly",
"You need to control how a collection is accessed and modified"
],
"when_not_to_use": [],
"symptoms": [
"Clients directly adding or removing elements from a returned collection",
"Internal collection state becoming inconsistent without the owning class knowing"
],
"benefits": [
"Prevents uncontrolled modification of internal collection state",
"Allows the class to maintain invariants when the collection changes",
"Encapsulates the actual collection type, enabling future implementation changes"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-024": {
"id": "RF-024",
"type": "refactoring",
"file_path": "refactoring/organizing-data/encapsulate-field.md",
"title": "Encapsulate Field",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-07"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A public field is accessed directly by external code",
"You need to add validation, logging, or side effects to field access",
"Encapsulation of internal state is a design goal"
],
"when_not_to_use": [],
"symptoms": [
"Public fields that are accessed directly from outside the class",
"No validation or invariants enforced when field values change"
],
"benefits": [
"Enables adding validation, notifications, or lazy initialization on access",
"Hides the internal representation, allowing future changes without breaking clients",
"Establishes a clear API boundary for the class"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-025": {
"id": "RF-025",
"type": "refactoring",
"file_path": "refactoring/organizing-data/replace-array-with-object.md",
"title": "Replace Array With Object",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-03"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-026",
"RF-032"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"An array is used to store heterogeneous data accessed by numeric index",
"Array index positions have named semantic meaning but the code uses magic numbers",
"You need to add behavior to data currently stored in array elements"
],
"when_not_to_use": [],
"symptoms": [
"Array accesses like data[2] or data[STATUS_INDEX] that require comments to explain",
"Arrays containing different types of data at different indices"
],
"benefits": [
"Replaces opaque index-based access with named fields for clarity",
"Allows adding behavior to the data structure as methods",
"Makes the code self-documenting by replacing magic numbers with field names"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-026": {
"id": "RF-026",
"type": "refactoring",
"file_path": "refactoring/organizing-data/replace-data-value-with-object.md",
"title": "Replace Data Value With Object",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-03"
],
"enforces": [
"LAW-040"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A simple data value like a string or number needs associated behavior or additional data",
"A primitive value has special domain meaning that deserves its own type",
"You need to add validation, formatting, or operations to a data item"
],
"when_not_to_use": [],
"symptoms": [
"Primitive values (strings, numbers) with special domain meaning passed around",
"Duplicated validation or formatting code for the same kind of data value"
],
"benefits": [
"Creates a rich domain type that encapsulates behavior alongside data",
"Enables type-safe APIs that prevent mixing up similar primitive values",
"Allows adding validation and business rules specific to the value"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-027": {
"id": "RF-027",
"type": "refactoring",
"file_path": "refactoring/organizing-data/replace-magic-number-with-symbolic-constant.md",
"title": "Replace Magic Number With Symbolic Constant",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-13"
],
"enforces": [
"LAW-040",
"LAW-041"
],
"violates": [],
"related_to": [
"RF-001",
"RF-026"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Numeric literals with special meaning appear in code without explanation",
"The same constant value is used in multiple places",
"You need to change a constant value and want a single point of modification"
],
"when_not_to_use": [],
"symptoms": [
"Unexplained numeric literals scattered throughout the code",
"The same constant value repeated in multiple locations"
],
"benefits": [
"Replaces magic numbers with self-documenting symbolic names",
"Centralizes the definition so changes are made in one place",
"Makes the code's intent clear without needing comments"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-028": {
"id": "RF-028",
"type": "refactoring",
"file_path": "refactoring/organizing-data/replace-subclass-with-fields.md",
"title": "Replace Subclass With Fields",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-12"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-031",
"RF-057"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Subclasses differ only in data (fields) but share the same behavior",
"You want to eliminate unnecessary subclass proliferation driven by constant data",
"Fields on a superclass can capture the variation that subclasses express"
],
"when_not_to_use": [],
"symptoms": [
"Subclasses that only differ in hardcoded values returned by overridden methods",
"A proliferation of trivial subclasses that each represent a single data variant"
],
"benefits": [
"Eliminates subclasses that add no behavioral variation",
"Simplifies the class hierarchy and reduces the number of classes",
"Makes it easy to add new variants without creating new subclasses"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-029": {
"id": "RF-029",
"type": "refactoring",
"file_path": "refactoring/organizing-data/replace-type-code-with-class.md",
"title": "Replace Type Code With Class",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A type code is represented as a primitive (integer, string) with no compile-time safety",
"Switch statements branch on the type code value throughout the code",
"You need to enforce valid values and prevent invalid type codes"
],
"when_not_to_use": [],
"symptoms": [
"Integer or string constants used to represent different types or categories",
"No compile-time checking for valid type code values"
],
"benefits": [
"Provides compile-time safety for type codes, preventing invalid values",
"Creates a named type that documents the valid options",
"Enables future refactorings like Replace Type Code With Subclasses or State/Strategy"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-030": {
"id": "RF-030",
"type": "refactoring",
"file_path": "refactoring/organizing-data/replace-type-code-with-state-strategy.md",
"title": "Replace Type Code With State Strategy",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O",
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-029",
"RF-031"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A type code affects class behavior and the values change at runtime",
"Switch statements on a type code field need to be replaced with polymorphic behavior",
"The State or Strategy pattern is the right fit for the varying behavior"
],
"when_not_to_use": [],
"symptoms": [
"Complex switch or if-else chains on a type code that affect behavior",
"Type code values that change during the lifetime of an object"
],
"benefits": [
"Replaces conditional logic with polymorphic dispatch for cleaner code",
"Allows the type-specific behavior to change at runtime",
"Makes it easy to add new types without modifying existing conditional code"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-031": {
"id": "RF-031",
"type": "refactoring",
"file_path": "refactoring/organizing-data/replace-type-code-with-subclasses.md",
"title": "Replace Type Code With Subclasses",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-06"
],
"enforces": [
"LAW-042-O"
],
"violates": [],
"related_to": [
"RF-029",
"RF-030"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A type code is fixed at object creation and never changes",
"Each type code variant has distinct behavior that should be in its own class",
"You want to use polymorphism to handle type-specific behavior"
],
"when_not_to_use": [],
"symptoms": [
"Switch statements on a type code that never changes after construction",
"Methods that branch behavior based on an immutable type code field"
],
"benefits": [
"Enables polymorphic dispatch to replace conditional logic on type codes",
"Each subclass encapsulates its variant-specific behavior",
"Makes adding new variants straightforward by creating new subclasses"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-032": {
"id": "RF-032",
"type": "refactoring",
"file_path": "refactoring/organizing-data/self-encapsulate-field.md",
"title": "Self Encapsulate Field",
"category": "organizing_data",
"tags": [],
"relations": {
"solves": [
"SMELL-07"
],
"enforces": [
"LAW-040",
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A subclass accesses a superclass field directly but you need more flexibility",
"You want to introduce lazy initialization or validation on field access",
"Direct field access across inheritance levels makes future changes difficult"
],
"when_not_to_use": [],
"symptoms": [
"Subclasses directly accessing inherited fields without going through accessors",
"A field's representation needs to change but subclasses depend on direct access"
],
"benefits": [
"Decouples subclasses from the superclass's internal representation",
"Enables lazy initialization, validation, or caching in the accessor",
"Allows changing the field's representation without breaking subclasses"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-033": {
"id": "RF-033",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/consolidate-conditional-expression.md",
"title": "Consolidate Conditional Expression",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-21"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Multiple conditions in a sequence check related things and combine to a single result",
"A complex boolean expression can be simplified by naming its parts",
"You want to extract the combined condition into a well-named method"
],
"when_not_to_use": [],
"symptoms": [
"A sequence of conditions combined with AND/OR that is hard to read",
"Complex boolean expressions that require comments to explain"
],
"benefits": [
"Names the combined condition, making the intent self-documenting",
"Simplifies complex boolean expressions into a single readable call",
"Makes it easy to reuse the condition or modify it in one place"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-034": {
"id": "RF-034",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/consolidate-duplicate-conditional-fragments.md",
"title": "Consolidate Duplicate Conditional Fragments",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-01",
"SMELL-13"
],
"enforces": [
"LAW-040",
"LAW-041"
],
"violates": [],
"related_to": [
"RF-033",
"RF-035"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"The same code appears in all branches of a conditional",
"Duplicated code in if/else blocks can be moved outside the conditional",
"Conditional branches contain identical setup or teardown code"
],
"when_not_to_use": [],
"symptoms": [
"Identical code appearing in every branch of an if/else or switch",
"Setup or cleanup code copied into all conditional branches"
],
"benefits": [
"Eliminates code duplication across conditional branches",
"Clarifies what is truly conditional versus what is common logic",
"Reduces the chance of updating one branch but forgetting another"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-035": {
"id": "RF-035",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/decompose-conditional.md",
"title": "Decompose Conditional",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-01",
"SMELL-06",
"SMELL-16",
"SMELL-21"
],
"enforces": [
"LAW-041",
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-033",
"RF-034",
"RF-040"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A complex conditional expression makes the code hard to follow",
"The condition, then-branch, and else-branch each represent distinct concepts",
"You want to name each part of the conditional for readability"
],
"when_not_to_use": [],
"symptoms": [
"A complex conditional with a large condition expression and substantial branches",
"Code where the reader must study the details to understand the branching logic"
],
"benefits": [
"Replaces complex if/else logic with clearly named method calls",
"Separates the condition, then-action, and else-action into distinct methods",
"Makes the overall logic of the conditional self-documenting"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-036": {
"id": "RF-036",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/introduce-assertion.md",
"title": "Introduce Assertion",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-025",
"LAW-041"
],
"violates": [],
"related_to": [
"RF-051"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"An assumption about state must hold for code to work correctly",
"You want to document and enforce a precondition explicitly",
"Checking a condition and throwing an error is too heavy; an assertion documents intent"
],
"when_not_to_use": [],
"symptoms": [
"Implicit assumptions about state that would cause subtle bugs if violated",
"Comments like 'this must never be null' that could instead be assertions"
],
"benefits": [
"Documents assumptions explicitly in code rather than in comments",
"Catches programming errors early by validating preconditions at runtime",
"Can be enabled or disabled for production versus development builds"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-037": {
"id": "RF-037",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/introduce-null-object.md",
"title": "Introduce Null Object",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-06",
"SMELL-08"
],
"enforces": [
"LAW-041"
],
"violates": [],
"related_to": [
"DP-020"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Repeated null checks for the same type appear throughout the codebase",
"You need a default or 'do nothing' behavior instead of null-handling logic",
"The domain has a meaningful concept of 'absent' or 'none' that null does not express well"
],
"when_not_to_use": [],
"symptoms": [
"Repeated if (x != null) checks scattered across many methods",
"Code cluttered with null-guard logic that obscures the real business logic"
],
"benefits": [
"Eliminates repeated null-check boilerplate throughout the codebase",
"Provides a safe default behavior that does nothing, avoiding NullPointerExceptions",
"Makes the domain concept of 'no value' explicit as a real object"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-038": {
"id": "RF-038",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/remove-control-flag.md",
"title": "Remove Control Flag",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-041"
],
"violates": [],
"related_to": [
"RF-035",
"RF-040"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A boolean variable is used as a control flag to manage loop or method flow",
"Break or return statements would make the control flow clearer",
"A variable is checked in conditionals purely to signal 'stop processing'"
],
"when_not_to_use": [],
"symptoms": [
"Boolean flags like 'isDone' or 'found' that only control loop or method termination",
"Nested conditions inside loops that check a control flag variable"
],
"benefits": [
"Replaces indirect control flow with explicit break, return, or guard clauses",
"Makes loop and method exit conditions immediately visible",
"Eliminates state-tracking variables that add complexity without adding clarity"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-039": {
"id": "RF-039",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/replace-conditional-with-polymorphism.md",
"title": "Replace Conditional With Polymorphism",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-04",
"SMELL-06"
],
"enforces": [
"LAW-040",
"LAW-041"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Switch or if-else statements branch on a type code to invoke different behavior",
"New types are frequently added, requiring changes to many conditional blocks",
"Behavior varies by type and each variant should own its own logic"
],
"when_not_to_use": [],
"symptoms": [
"Switch statements on a type code that appear in multiple methods",
"Adding a new type requires finding and updating many conditional blocks"
],
"benefits": [
"Replaces conditional dispatch with polymorphism for cleaner extensibility",
"Adding a new type only requires a new subclass, not modifying existing conditionals",
"Moves type-specific behavior to where it belongs: the type itself"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-040": {
"id": "RF-040",
"type": "refactoring",
"file_path": "refactoring/simplifying-conditionals/replace-nested-conditional-with-guard-clauses.md",
"title": "Replace Nested Conditional With Guard Clauses",
"category": "simplifying_conditionals",
"tags": [],
"relations": {
"solves": [
"SMELL-01",
"SMELL-21"
],
"enforces": [
"LAW-041",
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-035",
"RF-038"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Deeply nested if-else blocks make the control flow hard to follow",
"Special cases at the start of a method should exit early rather than indent",
"The normal flow is obscured by error-checking or edge-case handling"
],
"when_not_to_use": [],
"symptoms": [
"Arrow-shaped code with deep nesting levels for error or edge-case handling",
"The main logic buried inside multiple levels of if-else blocks"
],
"benefits": [
"Flattens nested conditionals into a linear sequence of early exits",
"Highlights the normal happy path by removing it from deep nesting",
"Makes each special case independently readable at the top of the method"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-041": {
"id": "RF-041",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/add-parameter.md",
"title": "Add Parameter",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-041"
],
"violates": [],
"related_to": [
"RF-043",
"RF-044",
"RF-046"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method needs additional information from its caller to perform its task",
"The method signature does not provide enough context for the required behavior",
"You want to generalize a method to handle variations via additional inputs"
],
"when_not_to_use": [],
"symptoms": [
"Methods that access global or shared state to get information they should receive as input",
"Near-duplicate methods that differ only in a single value or flag"
],
"benefits": [
"Enables methods to handle a wider range of scenarios with additional context",
"Avoids creating near-duplicate methods that differ only in one input value",
"Makes the method's dependencies explicit in its signature"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-042": {
"id": "RF-042",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/hide-method.md",
"title": "Hide Method",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-12"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-024",
"RF-032"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method is intended only for internal class use but is publicly visible",
"You want to reduce the public API surface of a class",
"A method that was public is now only called from within the class"
],
"when_not_to_use": [],
"symptoms": [
"Public methods that are never called from outside the class",
"A large public API that exposes implementation details unnecessarily"
],
"benefits": [
"Reduces the public API surface, making the class easier to understand and use",
"Signals that a method is an implementation detail, not a commitment",
"Enables freer refactoring of internal methods without breaking external callers"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-043": {
"id": "RF-043",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/introduce-parameter-object.md",
"title": "Introduce Parameter Object",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-02",
"SMELL-05"
],
"enforces": [
"LAW-040",
"LAW-041"
],
"violates": [],
"related_to": [
"RF-025",
"RF-044",
"RF-045"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Several methods share a common group of parameters that always appear together",
"A parameter list is long and many parameters are related",
"You want to use the grouped parameters as a first-class concept in the design"
],
"when_not_to_use": [],
"symptoms": [
"The same group of parameters repeated across multiple method signatures",
"Long parameter lists that are hard to remember and easy to mix up"
],
"benefits": [
"Reduces parameter list length and groups related data into a single object",
"Makes the parameter group reusable across methods as a first-class concept",
"Enables adding new fields to the group without changing method signatures"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-044": {
"id": "RF-044",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/parameterize-method.md",
"title": "Parameterize Method",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-13"
],
"enforces": [
"LAW-040",
"LAW-042-O"
],
"violates": [],
"related_to": [
"RF-043",
"RF-052"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Several methods do similar things but differ by one or two values",
"You want to replace near-duplicate methods with a single parameterized version",
"Adding a new variant would otherwise require creating yet another method"
],
"when_not_to_use": [],
"symptoms": [
"Multiple methods with similar names and nearly identical implementations",
"Methods like setValueFive, setValueTen, setValueTwenty that differ only in a constant"
],
"benefits": [
"Eliminates near-duplicate methods that differ only in constant values",
"Makes adding new variants trivial by passing a different parameter value",
"Reduces total code volume and maintenance burden"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-045": {
"id": "RF-045",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/preserve-whole-object.md",
"title": "Preserve Whole Object",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-02",
"SMELL-05",
"SMELL-18"
],
"enforces": [
"LAW-041",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-043"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"You are passing individual fields from an object to a method when you could pass the whole object",
"A method receives several values that all come from the same source object",
"You want to avoid long parameter lists derived from one object's fields"
],
"when_not_to_use": [],
"symptoms": [
"Method calls that extract multiple fields from one object to pass as separate arguments",
"Long parameter lists where most parameters come from the same source object"
],
"benefits": [
"Shortens parameter lists by passing a single object instead of multiple fields",
"Makes the method resilient to changes in which fields it needs from the object",
"Avoids the temptation to modify the source object to pass more data"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-046": {
"id": "RF-046",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/remove-parameter.md",
"title": "Remove Parameter",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [],
"enforces": [
"LAW-040"
],
"violates": [],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A parameter is no longer used by a method's body",
"The method signature carries parameters that callers pass but the method ignores",
"You want to simplify the method's API by removing unused inputs"
],
"when_not_to_use": [],
"symptoms": [
"Parameters that are received but never referenced in the method body",
"Callers computing values only to pass them to methods that ignore them"
],
"benefits": [
"Simplifies the method signature and makes it easier to understand",
"Removes the burden on callers of passing unnecessary arguments",
"Clarifies what the method actually depends on"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-047": {
"id": "RF-047",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/remove-setting-method.md",
"title": "Remove Setting Method",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-07"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-024",
"RF-042"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A setting method is called only at construction time and the value should not change",
"You want to make a field immutable after construction",
"A setter exposes the ability to change state that should be fixed at birth"
],
"when_not_to_use": [],
"symptoms": [
"Setter methods called only in the constructor and nowhere else",
"Fields that logically should never change but have a public setter"
],
"benefits": [
"Enforces immutability of fields that should not change after construction",
"Makes the object's state more predictable and easier to reason about",
"Reduces the public API and signals that the value is fixed"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-048": {
"id": "RF-048",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/rename-method.md",
"title": "Rename Method",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-23"
],
"enforces": [
"LAW-031",
"LAW-044"
],
"violates": [],
"related_to": [
"RF-041",
"RF-046"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method name does not clearly convey what the method does",
"The name is inconsistent with naming conventions or other method names in the codebase",
"You need to rename to make the code self-documenting"
],
"when_not_to_use": [],
"symptoms": [
"Method names that are cryptic, abbreviated, or misleading",
"Readers who must look at the method body to understand what it does"
],
"benefits": [
"Makes the code self-documenting by using descriptive, intention-revealing names",
"Improves discoverability and reduces the need to read the method body",
"Aligns naming with domain language for better communication"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-049": {
"id": "RF-049",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/replace-constructor-with-factory-method.md",
"title": "Replace Constructor With Factory Method",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-21"
],
"enforces": [
"LAW-042-D"
],
"violates": [],
"related_to": [
"RF-010",
"RF-056"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Object creation logic is complex or needs to vary based on conditions",
"You want to encapsulate construction to hide concrete class names from callers",
"Subclasses need to control which instances get created"
],
"when_not_to_use": [],
"symptoms": [
"Complex construction logic repeated at multiple call sites",
"Callers that know too much about which concrete class to instantiate"
],
"benefits": [
"Encapsulates complex creation logic in a single, well-named method",
"Decouples client code from concrete class names",
"Enables returning different subtypes or cached instances from the same call"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-050": {
"id": "RF-050",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/replace-error-code-with-exception.md",
"title": "Replace Error Code With Exception",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-027",
"LAW-044"
],
"violates": [],
"related_to": [
"RF-051"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method returns an error code that the caller must check explicitly",
"Error conditions should propagate up the call stack automatically",
"You want to use language-native exception handling for error flow"
],
"when_not_to_use": [],
"symptoms": [
"Methods returning error codes that callers forget to check",
"Complex if-else chains dedicated to error propagation instead of business logic"
],
"benefits": [
"Separates error handling from normal control flow for cleaner code",
"Ensures errors cannot be silently ignored by callers",
"Leverages language-native exception propagation to unwind the call stack"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-051": {
"id": "RF-051",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/replace-exception-with-test.md",
"title": "Replace Exception With Test",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-041"
],
"violates": [],
"related_to": [
"RF-036",
"RF-050"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Exceptions are used for ordinary control flow rather than genuine error conditions",
"A try-catch block handles a condition that could be tested with an if-statement",
"Performance-critical code where exception overhead is unacceptable for expected cases"
],
"when_not_to_use": [],
"symptoms": [
"Exceptions caught and handled as part of normal program logic",
"Try-catch blocks where the catch implements expected behavior, not error recovery"
],
"benefits": [
"Replaces expensive exception-based control flow with a simple conditional test",
"Makes the expected case the normal flow rather than an exceptional one",
"Clarifies that the condition is a business rule, not an error"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-052": {
"id": "RF-052",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/replace-parameter-with-explicit-methods.md",
"title": "Replace Parameter With Explicit Methods",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-01"
],
"enforces": [
"LAW-041",
"LAW-044"
],
"violates": [],
"related_to": [
"RF-044",
"RF-053"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method takes a parameter that selects between different behaviors",
"Switch-like parameter dispatch makes the method do fundamentally different things",
"Each value of a parameter corresponds to a distinct, named operation"
],
"when_not_to_use": [],
"symptoms": [
"Methods that switch on a parameter to decide what to do",
"Method names paired with 'mode' or 'type' parameters to select behavior"
],
"benefits": [
"Replaces a single multi-purpose method with clearly named, single-purpose methods",
"Makes the API more discoverable and self-documenting",
"Enables compile-time checking that the right method is called"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-053": {
"id": "RF-053",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/replace-parameter-with-method-call.md",
"title": "Replace Parameter With Method Call",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-02"
],
"enforces": [
"LAW-040",
"LAW-041"
],
"violates": [],
"related_to": [
"RF-045",
"RF-052"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method receives a parameter that could be obtained by calling another method on the receiver",
"The caller computes a value just to pass it, when the callee could compute it itself",
"You want to reduce coupling by removing unnecessary parameter passing"
],
"when_not_to_use": [],
"symptoms": [
"Parameters that are just the result of calling another method available to the callee",
"Callers fetching data solely to pass it into a method that could get it directly"
],
"benefits": [
"Eliminates unnecessary parameters that add coupling without adding value",
"Reduces the burden on callers to compute and pass values the callee can obtain itself",
"Makes the method more self-sufficient and its dependencies clearer"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-054": {
"id": "RF-054",
"type": "refactoring",
"file_path": "refactoring/simplifying-calls/separate-query-from-modifier.md",
"title": "Separate Query From Modifier",
"category": "simplifying_calls",
"tags": [],
"relations": {
"solves": [
"SMELL-01",
"SMELL-21"
],
"enforces": [
"LAW-042-S",
"LAW-044"
],
"violates": [],
"related_to": [
"RF-001",
"RF-042"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method both returns a value and modifies object state",
"You need to optimize or cache the query result without affecting mutation logic",
"Readers cannot tell from the signature whether calling the method is safe or has side effects"
],
"when_not_to_use": [],
"symptoms": [
"Methods that both change state and return a value, confusing callers about side effects",
"Bug reports where a 'harmless' getter unexpectedly modified state"
],
"benefits": [
"Clearly separates read operations from write operations for predictability",
"Allows the query to be called freely without fear of side effects",
"Enables independent optimization of the query and the modifier"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-055": {
"id": "RF-055",
"type": "refactoring",
"file_path": "refactoring/generalization/collapse-hierarchy.md",
"title": "Collapse Hierarchy",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-11",
"SMELL-12",
"SMELL-22"
],
"enforces": [
"LAW-041"
],
"violates": [],
"related_to": [
"RF-012",
"RF-057",
"RF-058"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A superclass and its subclass are so similar that the hierarchy adds no value",
"A subclass was created for a variation that no longer exists or is negligible",
"Merging the two classes would simplify the design without losing expressiveness"
],
"when_not_to_use": [],
"symptoms": [
"A subclass that adds minimal or no behavior beyond the superclass",
"An inheritance hierarchy where a level can be removed without losing functionality"
],
"benefits": [
"Eliminates unnecessary hierarchy levels, reducing code complexity",
"Consolidates related logic into a single class for easier maintenance",
"Removes the overhead of managing a trivial inheritance relationship"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-056": {
"id": "RF-056",
"type": "refactoring",
"file_path": "refactoring/generalization/extract-interface.md",
"title": "Extract Interface",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-09",
"SMELL-21",
"SMELL-23"
],
"enforces": [
"LAW-042-D",
"LAW-042-I"
],
"violates": [],
"related_to": [
"RF-010",
"RF-057",
"RF-058"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Multiple clients depend on the same subset of a class's interface",
"You need to define a contract that multiple classes can implement",
"You want to decouple clients from specific implementations"
],
"when_not_to_use": [],
"symptoms": [
"Clients depending on concrete classes when they only need a subset of behavior",
"Unrelated classes that share common method signatures without a shared type"
],
"benefits": [
"Defines a clear contract that multiple implementations can fulfill",
"Decouples clients from concrete classes, enabling dependency inversion",
"Supports polymorphism across unrelated classes that share common behavior"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-057": {
"id": "RF-057",
"type": "refactoring",
"file_path": "refactoring/generalization/extract-subclass.md",
"title": "Extract Subclass",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-04",
"SMELL-22"
],
"enforces": [
"LAW-042-L",
"LAW-042-O"
],
"violates": [],
"related_to": [
"RF-010",
"RF-056",
"RF-058"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A class has features that apply only to some instances, not all",
"You need to represent variant behavior or data for specific cases",
"Some objects of a class need additional methods or fields that others do not"
],
"when_not_to_use": [],
"symptoms": [
"Fields or methods guarded by type checks that apply only to certain instances",
"A class where some features are only relevant for a subset of its instances"
],
"benefits": [
"Isolates variant-specific behavior into its own class",
"Keeps the base class focused on common behavior",
"Makes adding new variants straightforward by creating new subclasses"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-058": {
"id": "RF-058",
"type": "refactoring",
"file_path": "refactoring/generalization/extract-superclass.md",
"title": "Extract Superclass",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-04",
"SMELL-13"
],
"enforces": [
"LAW-040",
"LAW-042-L"
],
"violates": [],
"related_to": [
"RF-056",
"RF-057",
"RF-061"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Two or more classes share common fields and methods that could be unified",
"Duplicate code exists across classes that are conceptually related",
"You want to create a common abstraction for related classes"
],
"when_not_to_use": [],
"symptoms": [
"Duplicate fields and methods across two or more related classes",
"Classes that share a conceptual identity but lack a common ancestor"
],
"benefits": [
"Eliminates duplication by pulling common elements into a shared superclass",
"Creates a clear abstraction that captures the shared concept",
"Enables polymorphism and shared behavior across related classes"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-059": {
"id": "RF-059",
"type": "refactoring",
"file_path": "refactoring/generalization/form-template-method.md",
"title": "Form Template Method",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-13"
],
"enforces": [
"LAW-040",
"LAW-042-L"
],
"violates": [],
"related_to": [
"RF-058",
"RF-062"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Subclasses have methods with similar structure but different steps",
"An algorithm skeleton is shared but individual steps vary by subclass",
"You want to define the invariant parts of an algorithm in one place"
],
"when_not_to_use": [],
"symptoms": [
"Methods in different subclasses with identical structure but different details",
"Similar algorithmic steps duplicated with minor variations across subclasses"
],
"benefits": [
"Defines the invariant algorithm skeleton in the superclass",
"Allows subclasses to override only the varying steps",
"Eliminates structural duplication across similar subclass methods"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-060": {
"id": "RF-060",
"type": "refactoring",
"file_path": "refactoring/generalization/pull-up-constructor-body.md",
"title": "Pull Up Constructor Body",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-13"
],
"enforces": [
"LAW-040"
],
"violates": [],
"related_to": [
"RF-058",
"RF-061",
"RF-062"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Subclasses share identical constructor initialization logic",
"Common initialization code is duplicated across subclass constructors",
"You want to centralize field initialization in the superclass"
],
"when_not_to_use": [],
"symptoms": [
"Identical initialization code repeated in multiple subclass constructors",
"Subclass constructors that copy-paste the same field assignments"
],
"benefits": [
"Eliminates duplicate initialization code across subclass constructors",
"Centralizes common setup logic in the superclass constructor",
"Ensures consistent initialization behavior across all subclasses"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-061": {
"id": "RF-061",
"type": "refactoring",
"file_path": "refactoring/generalization/pull-up-field.md",
"title": "Pull Up Field",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-13"
],
"enforces": [
"LAW-040"
],
"violates": [],
"related_to": [
"RF-058",
"RF-060",
"RF-062"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Fields are duplicated in multiple subclasses and represent the same concept",
"You want to access a common field through the superclass type",
"Shared field declarations should be centralized to avoid duplication"
],
"when_not_to_use": [],
"symptoms": [
"The same field declared independently in multiple subclasses",
"Duplicated getter/setter logic for the same conceptual field in different subclasses"
],
"benefits": [
"Eliminates field duplication across subclasses",
"Allows access to the field through the superclass interface",
"Centralizes field-related behavior in the superclass"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-062": {
"id": "RF-062",
"type": "refactoring",
"file_path": "refactoring/generalization/pull-up-method.md",
"title": "Pull Up Method",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-13"
],
"enforces": [
"LAW-040",
"LAW-042-L"
],
"violates": [],
"related_to": [
"RF-059",
"RF-060",
"RF-061"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"Methods with identical or very similar behavior exist in multiple subclasses",
"You want to invoke the behavior through the superclass type",
"Common method implementations should be shared rather than duplicated"
],
"when_not_to_use": [],
"symptoms": [
"Identical or nearly identical methods implemented in multiple subclasses",
"Duplicated logic that could be shared through the superclass"
],
"benefits": [
"Eliminates duplicate method implementations across subclasses",
"Allows the method to be called through the superclass interface",
"Centralizes behavior in one place so changes are made once"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-063": {
"id": "RF-063",
"type": "refactoring",
"file_path": "refactoring/generalization/push-down-field.md",
"title": "Push Down Field",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-04"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-061",
"RF-064"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A field is used only by some subclasses but not all",
"Features related to the field are specific to a subset of subclasses",
"You want to move specialized data to where it is actually needed"
],
"when_not_to_use": [],
"symptoms": [
"Fields that are meaningful only for certain subclasses but declared in the superclass",
"Subclasses where a field is always null or unused"
],
"benefits": [
"Removes unused fields from classes that do not need them",
"Keeps each class focused on the data it actually uses",
"Makes the class hierarchy more precise and reduces memory footprint"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-064": {
"id": "RF-064",
"type": "refactoring",
"file_path": "refactoring/generalization/push-down-method.md",
"title": "Push Down Method",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-04"
],
"enforces": [
"LAW-042-S"
],
"violates": [],
"related_to": [
"RF-062",
"RF-063"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A method in the superclass is only relevant to some subclasses",
"Subclasses provide irrelevant or no-op implementations of a method",
"You want each subclass to own only the behavior it actually needs"
],
"when_not_to_use": [],
"symptoms": [
"Subclasses that provide empty or trivial implementations of inherited methods",
"Methods in the superclass that only some subclasses meaningfully override"
],
"benefits": [
"Moves behavior to where it is relevant, improving cohesion",
"Eliminates no-op or irrelevant method implementations in subclasses",
"Makes the superclass's API more focused on truly common behavior"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-065": {
"id": "RF-065",
"type": "refactoring",
"file_path": "refactoring/generalization/replace-delegation-with-inheritance.md",
"title": "Replace Delegation With Inheritance",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-14"
],
"enforces": [
"LAW-042-L"
],
"violates": [],
"related_to": [
"RF-011",
"RF-066"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A class delegates all methods to another class and is effectively a subclass",
"The delegation relationship mirrors what inheritance would express more naturally",
"You want to replace wrapper methods with inherited behavior"
],
"when_not_to_use": [],
"symptoms": [
"A class whose every method delegates to the same object",
"Delegation that exists solely because inheritance was not used from the start"
],
"benefits": [
"Replaces verbose delegation with concise inheritance",
"Leverages polymorphism and standard OO mechanisms",
"Reduces boilerplate delegation code"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"RF-066": {
"id": "RF-066",
"type": "refactoring",
"file_path": "refactoring/generalization/replace-inheritance-with-delegation.md",
"title": "Replace Inheritance With Delegation",
"category": "generalization",
"tags": [],
"relations": {
"solves": [
"SMELL-19"
],
"enforces": [
"LAW-042-S",
"LAW-043"
],
"violates": [],
"related_to": [
"RF-011",
"RF-065"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [
"A subclass uses only part of a superclass's interface or behaves inconsistently",
"Inheritance is being misused: the subclass is-not-a genuine specialization",
"Delegation would better express the relationship between the two classes"
],
"when_not_to_use": [],
"symptoms": [
"A subclass that overrides methods to throw UnsupportedOperationException or do nothing",
"Inheritance where the subclass is-not-a true specialization of the superclass"
],
"benefits": [
"Replaces inappropriate inheritance with a more flexible delegation relationship",
"Allows the former subclass to use only the parts of the delegate it actually needs",
"Reduces coupling and prevents Liskov Substitution Principle violations"
],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"SMELL-01": {
"id": "SMELL-01",
"type": "smell",
"title": "Long Method",
"category": "bloater",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S",
"LAW-041"
],
"related_to": [
"SMELL-16"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Method exceeds 20-30 lines",
"Multiple levels of nesting",
"Requires inline comments to explain sections"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/long-method.md"
},
"SMELL-02": {
"id": "SMELL-02",
"type": "smell",
"title": "Long Parameter List",
"category": "bloater",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-041"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Method has more than 3-4 parameters",
"Parameter list keeps growing",
"Parameters form natural groups"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/long-parameter-list.md"
},
"SMELL-03": {
"id": "SMELL-03",
"type": "smell",
"title": "Primitive Obsession",
"category": "bloater",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Using primitives for domain concepts",
"Simulation of types via constants",
"Type code as field names"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/primitive-obsession.md"
},
"SMELL-04": {
"id": "SMELL-04",
"type": "smell",
"title": "Large Class",
"category": "bloater",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [
"SMELL-08",
"SMELL-22"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Class exceeds 200-300 lines",
"Multiple unrelated responsibilities",
"High instance variable count"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/large-class.md"
},
"SMELL-05": {
"id": "SMELL-05",
"type": "smell",
"title": "Data Clumps",
"category": "bloater",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [
"LAW-042"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Same group of parameters in multiple methods",
"Same fields in multiple classes",
"Grouped data used together"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/data-clumps.md"
},
"SMELL-06": {
"id": "SMELL-06",
"type": "smell",
"title": "Switch Statements",
"category": "oo-abuser",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-O"
],
"related_to": [
"LAW-042"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Switch on type code",
"Same switch duplicated across methods",
"New cases require modification"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/switch-statements.md"
},
"SMELL-13": {
"id": "SMELL-13",
"type": "smell",
"title": "Duplicate Code",
"category": "dispensable",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [
"SMELL-15",
"SMELL-23"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Identical expressions in multiple methods",
"Similar code in sibling subclasses",
"Copied and pasted code"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/duplicate-code.md"
},
"SMELL-18": {
"id": "SMELL-18",
"type": "smell",
"title": "Feature Envy",
"category": "coupler",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-043"
],
"related_to": [
"LAW-042"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Method uses many getters from another class",
"Method is more interested in other class than its own",
"Method manipulates foreign data"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/feature-envy.md"
},
"SMELL-19": {
"id": "SMELL-19",
"type": "smell",
"title": "Inappropriate Intimacy",
"category": "coupler",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-043"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Classes access each other's private fields/methods",
"Bidirectional dependencies",
"Excessive coupling"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/inappropriate-intimacy.md"
},
"SMELL-20": {
"id": "SMELL-20",
"type": "smell",
"title": "Message Chains",
"category": "coupler",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-043"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Long chains like a.getB().getC().getD()",
"Client depends on navigation structure",
"Changes ripple through chain"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/message-chains.md"
},
"SMELL-21": {
"id": "SMELL-21",
"type": "smell",
"title": "God Object",
"category": "bloater",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Class has excessive methods and fields",
"Class knows about or does everything",
"Changes always touch this class"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/god-object.md"
},
"SMELL-07": {
"id": "SMELL-07",
"type": "smell",
"title": "Data Class",
"category": "dispensable",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Class has only fields and getters/setters",
"No behavior methods",
"Other classes manipulate its data"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/data-class.md"
},
"SMELL-09": {
"id": "SMELL-09",
"type": "smell",
"title": "Shotgun Surgery",
"category": "change-preventer",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [
"SMELL-15"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"One change affects many classes",
"Related functionality scattered",
"Hard to find all places to change"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/shotgun-surgery.md"
},
"SMELL-10": {
"id": "SMELL-10",
"type": "smell",
"title": "Divergent Change",
"category": "change-preventer",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Class changes for multiple reasons",
"Different methods change for different features",
"Multiple responsibilities"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/divergent-change.md"
},
"SMELL-11": {
"id": "SMELL-11",
"type": "smell",
"title": "Lazy Class",
"category": "dispensable",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [
"SMELL-17"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Class does too little",
"Thin wrapper with minimal logic",
"Added for future use but never grown"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/lazy-class.md"
},
"SMELL-12": {
"id": "SMELL-12",
"type": "smell",
"title": "Speculative Generality",
"category": "dispensable",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [
"SMELL-17"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Abstract class with only one subclass",
"Unused parameters or hooks",
"Methods named to future-proof code"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/speculative-generality.md"
},
"SMELL-14": {
"id": "SMELL-14",
"type": "smell",
"title": "Middle Man",
"category": "coupler",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Most methods delegate to another class",
"Class adds no behavior of its own",
"Thin pass-through wrapper"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/middle-man.md"
},
"LAW-042-S": {
"id": "LAW-042-S",
"type": "law",
"file_path": "software-engineering/design/solid-principles.md",
"title": "Single Responsibility Principle",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-042-I"
],
"requires": [],
"enables": [],
"violated_by": []
},
"context": {
"when_to_use": [
"A class has multiple reasons to change driven by different business actors"
],
"when_not_to_use": [],
"symptoms": [
"Class changes for more than one reason",
"Large class with unrelated methods"
],
"benefits": [
"Localises change",
"Reduces regression risk"
],
"drawbacks": []
},
"source": {
"title": "Agile Software Development: Principles, Patterns, and Practices",
"authors": [
"Robert C. Martin"
],
"year": 2002,
"publisher": "Prentice Hall",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/SOLID"
}
},
"LAW-042-O": {
"id": "LAW-042-O",
"type": "law",
"file_path": "software-engineering/design/solid-principles.md",
"title": "Open/Closed Principle",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": [],
"violated_by": []
},
"context": {
"when_to_use": [
"Adding new behaviour requires modifying existing tested code"
],
"when_not_to_use": [],
"symptoms": [
"Every new feature requires editing the same class"
],
"benefits": [
"Extension without modification"
],
"drawbacks": []
},
"source": {
"title": "Agile Software Development: Principles, Patterns, and Practices",
"authors": [
"Robert C. Martin"
],
"year": 2002,
"publisher": "Prentice Hall",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/SOLID"
}
},
"LAW-042-L": {
"id": "LAW-042-L",
"type": "law",
"file_path": "software-engineering/design/solid-principles.md",
"title": "Liskov Substitution Principle",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": [],
"violated_by": []
},
"context": {
"when_to_use": [
"Subclass overrides base class behaviour in a way that breaks callers"
],
"when_not_to_use": [],
"symptoms": [
"Callers inspect concrete type at runtime",
"Square/Rectangle-style invariant violations"
],
"benefits": [
"Correct polymorphism",
"Safe substitution"
],
"drawbacks": []
},
"source": {
"title": "Agile Software Development: Principles, Patterns, and Practices",
"authors": [
"Robert C. Martin"
],
"year": 2002,
"publisher": "Prentice Hall",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/SOLID"
}
},
"LAW-042-I": {
"id": "LAW-042-I",
"type": "law",
"file_path": "software-engineering/design/solid-principles.md",
"title": "Interface Segregation Principle",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [
"LAW-042-S",
"DP-006"
],
"requires": [],
"enables": [],
"violated_by": []
},
"context": {
"when_to_use": [
"Clients depend on interface methods they never use"
],
"when_not_to_use": [],
"symptoms": [
"Clients import methods they do not call",
"Interface changes ripple to unrelated clients"
],
"benefits": [
"Narrow contracts",
"Reduced coupling"
],
"drawbacks": []
},
"source": {
"title": "Agile Software Development: Principles, Patterns, and Practices",
"authors": [
"Robert C. Martin"
],
"year": 2002,
"publisher": "Prentice Hall",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/SOLID"
}
},
"LAW-042-D": {
"id": "LAW-042-D",
"type": "law",
"file_path": "software-engineering/design/solid-principles.md",
"title": "Dependency Inversion Principle",
"category": "design",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [],
"related_to": [],
"requires": [],
"enables": [],
"violated_by": []
},
"context": {
"when_to_use": [
"High-level policy depends directly on low-level infrastructure"
],
"when_not_to_use": [],
"symptoms": [
"High-level modules import concrete infrastructure classes",
"Tests require real databases or services"
],
"benefits": [
"Testability",
"Infrastructure replaceability"
],
"drawbacks": []
},
"source": {
"title": "Agile Software Development: Principles, Patterns, and Practices",
"authors": [
"Robert C. Martin"
],
"year": 2002,
"publisher": "Prentice Hall",
"license": "reference",
"url": "https://en.wikipedia.org/wiki/SOLID"
}
},
"SMELL-22": {
"id": "SMELL-22",
"type": "smell",
"file_path": "code-smells/refused-bequest.md",
"title": "Refused Bequest",
"category": "inheritance",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-L"
],
"related_to": [
"SMELL-04"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Subclass inherits methods or data it does not use",
"Subclass overrides inherited behaviour to do nothing or throw",
"Base class carries baggage that only some subclasses need"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://refactoring.com/"
}
},
"SMELL-08": {
"id": "SMELL-08",
"type": "smell",
"title": "Temporary Field",
"category": "oo-abuser",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [
"SMELL-04"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Field is only set in specific code paths",
"Field is null or empty under normal conditions",
"Code checks whether field is set before using it"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/temporary-field.md"
},
"SMELL-15": {
"id": "SMELL-15",
"type": "smell",
"title": "Parallel Inheritance Hierarchies",
"category": "change-preventer",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-S"
],
"related_to": [
"SMELL-09",
"SMELL-13"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Two class hierarchies mirror each other",
"Adding a subclass in one hierarchy requires adding one in another",
"Class name prefixes are the same in both hierarchies"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/parallel-inheritance-hierarchies.md"
},
"SMELL-16": {
"id": "SMELL-16",
"type": "smell",
"title": "Comments",
"category": "dispensable",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [
"SMELL-01"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Long comment block explaining what the code does",
"Comment that would be unnecessary if the code were clearer",
"TODO or FIXME comments persisting without resolution"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/comments.md"
},
"SMELL-17": {
"id": "SMELL-17",
"type": "smell",
"title": "Dead Code",
"category": "dispensable",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-040"
],
"related_to": [
"SMELL-11",
"SMELL-12"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Unreachable code after a return or throw",
"Variables, methods, or classes that are never referenced",
"Commented-out code left in the codebase"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/dead-code.md"
},
"SMELL-23": {
"id": "SMELL-23",
"type": "smell",
"title": "Alternative Classes with Different Interfaces",
"category": "oo-abuser",
"tags": [],
"relations": {
"solves": [],
"enforces": [],
"violates": [
"LAW-042-I"
],
"related_to": [
"SMELL-13"
],
"requires": [],
"enables": []
},
"context": {
"when_to_use": [],
"when_not_to_use": [],
"symptoms": [
"Two classes do similar things but have different method names",
"Classes could be used interchangeably but lack a common interface",
"Clients must know which class to use and adapt to each"
],
"benefits": [],
"drawbacks": []
},
"source": {
"title": "Refactoring: Improving the Design of Existing Code",
"authors": [
"Martin Fowler"
],
"year": 1999,
"publisher": "Addison-Wesley",
"license": "reference",
"url": "https://martinfowler.com/books/refactoring.html"
},
"file_path": "code-smells/alternative-classes-with-different-interfaces.md"
}
}