Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/pr-check-managed-files-hosted.yml
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ on:
- docs/standards/README.md
- docs/standards/bulk-mutation.md
- docs/standards/concise-prose.md
- docs/standards/design-for-change.md
- docs/standards/deterministic-work-execution.md
- docs/standards/documentation-and-citations.md
- docs/standards/reference-dont-duplicate.md
Expand Down
1 change: 1 addition & 0 deletions docs/standards/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Team-layer engineering standards synced from melodic-software/standards
|---|---|---|
| bulk-mutation | a command or sweep that creates, deletes, or changes many objects; background or unattended runs; work spanning several targets | bulk-mutation.md |
| concise-prose | writing or reviewing any prose: docs, comments, commit messages, PR bodies, replies | concise-prose.md |
| design-for-change | designing or reviewing a module boundary, an extension point, configuration, dependency wiring, or a design pattern; any change whose reversal would edit many files | design-for-change.md |
| deterministic-work-execution | counts, diffs, sorting, arithmetic, inventories; composing shell commands an agent runs | deterministic-work-execution.md |
| documentation-and-citations | citing upstream docs; recording an external default or version; labeling the basis of a recommendation | documentation-and-citations.md |
| reference-dont-duplicate | a fact, value, or rule appearing in more than one place; origin or history notes in code or docs | reference-dont-duplicate.md |
Expand Down
45 changes: 45 additions & 0 deletions docs/standards/design-for-change.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Design for change

A design is judged by what a change of direction costs: how many files it touches and how far the breakage spreads. These rules let a reviewer check that cost on a diff. Each one applies where it makes sense: a rule that would add a mechanism with no present need yields to [simpler-code.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/simpler-code.md#build-only-what-someone-acts-on).

## Intent

The owner's direction, verbatim (2026-10-27):

<!-- spellchecker:off -->
> Also ensure we're aligned with SOLID, and DRY/SSOT principles. Changing directions later shouldn't result in cascading breakages, and require changes to more than a handful of files (impact), refactoring pain. We need to ensure things are configurable/extensibile and minimize that risk (our designs should accommodate for this).
>
> ...
>
> As far as designs - lets try and apply the tenants of vertical slice/feature slice architecture (where it makes sense). Feel free to use the common Gang of Four design patterns, like strategy, factory, builder, decorator, mediator, etc - along with the tenants/principles of dependency injection, externalized config, DRY/SSOT, clean code (Robert C Martin), and general modern software best practices.
<!-- spellchecker:on -->

## Rules

Each rule gives the check, why it holds, and its source.

1. **Hide each volatile decision in one module.** Check: a decision likely to change (a provider, store, wire or file format, transport, algorithm, or policy) is known to one module; callers depend on that module's contract, not on the decision. Why: the decision can then change by editing that one module. Source: [Parnas, "On the Criteria To Be Used in Decomposing Systems into Modules", CACM 15(12), 1972](https://doi.org/10.1145/361598.361623).
2. **A reversal stays local.** Check: for the decision the diff introduces, name the plausible reversal and count what it would edit. Swapping it should touch the owning module plus the composition root or configuration. A swap that would edit callers in other features means the decision leaked. Do not count the files a feature legitimately spans inside its own slice; that is the [shotgun-surgery carve-out](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#responsibility-and-cohesion). Why: "Gather together the things that change for the same reasons. Separate those things that change for different reasons." Source: [Martin, "The Single Responsibility Principle", 2014](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html); the Common Closure Principle in [Martin, "The Principles of OOD"](http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod).
3. **Slice by feature.** Check: a new feature lands in its own slice, and one slice does not import another slice's internals. The structure is owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#feature-and-vertical-slice-organization); when to share across slices by [code-organization.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/code-organization.md#share-at-the-second-consumer-never-copy). Why: "Minimize coupling between slices, and maximize coupling in a slice." Where it does not fit: Bogard warns the style assumes a team that recognizes code smells and refactors when a handler does too much. Source: [Bogard, "Vertical Slice Architecture", 2018](https://www.jimmybogard.com/vertical-slice-architecture/).
4. **Wire at the composition root; inject at volatile boundaries.** Check: business code receives a volatile collaborator through its constructor; it does not construct one or pull one from a service locator. Why: "the configuration of services is separated from their use." Dissent: Fowler himself gives Service Locator "a slight edge" inside one application and prefers injection for classes used by several; this catalog's default stays injection, per the [Hollywood Principle](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#let-the-framework-call-you-hollywood-principle). An interface for a stable in-process dependency is [needless indirection](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#abstraction-fit). Source: [Fowler, "Inversion of Control Containers and the Dependency Injection pattern", 2004](https://martinfowler.com/articles/injection.html).
5. **What varies by deploy is configuration.** Check: a value that differs between deploys (endpoints, credentials, per-environment settings) is read from configuration, not source; internal wiring that never varies stays in code. Why: config is "everything that is likely to vary between deploys." The YAGNI bound is owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#configurable-by-default-within-reason), and consumer-varying values by [shareable-artifact-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/shareable-artifact-design.md#externalize-what-a-consumer-may-decide). Source: [The Twelve-Factor App, III. Config](https://12factor.net/config).
6. **Add a variant by addition, not by edit.** Check: a new variant arrives as a new registration, strategy, or handler, not as another branch in shared dispatch. The bar and its YAGNI counterweight are owned by [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#open-for-extension-closed-for-modification) and reviewed under [code-design.md](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#pattern-application). Source: the Open-Closed Principle in [Martin, "The Principles of OOD"](http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod).
7. **A pattern names the variation it serves.** Check: a diff that introduces one of the patterns below names the present need from the "Fits when" column; with none, it is [premature patternization](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md#pattern-application). Why: each pattern adds classes and indirection that pay only when the variation exists. Source: [Gamma, Helm, Johnson, Vlissides, *Design Patterns*, Addison-Wesley, 1994](https://www.informit.com/store/design-patterns-elements-of-reusable-object-oriented-9780201633610), with the per-pattern pages below.
8. **DRY means one source per piece of knowledge, not per string.** Check: run the ordered tests in [reference-dont-duplicate.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/reference-dont-duplicate.md#consolidation-doctrine-ordered-tests) before consolidating; same text encoding different knowledge stays separate. An existing abstraction that is gaining a parameter or branch per caller is inlined back into its callers, not extended. Why: "duplication is far cheaper than the wrong abstraction." Source: [Metz, "The Wrong Abstraction", 2016](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction); [Dodds, "AHA Programming", 2020](https://kentcdodds.com/blog/aha-programming).
9. **Clean Code rules are heuristics.** Check: SOLID and *Clean Code* smells are reviewed under [code-design.md](https://github.com/melodic-software/standards/blob/main/conventions/review/code-design.md); a deviation on a measured hot path carries its measurement. Why: the book's rules are contested: its examples ([qntm, 2020](https://qntm.org/clean)), its performance cost ([Muratori, "Clean Code, Horrible Performance", 2023](https://www.computerenhance.com/p/clean-code-horrible-performance)), and SOLID itself ([North, "CUPID: for joyful coding", 2022](https://dannorth.net/blog/cupid-for-joyful-coding/)). Source: [Martin, *Clean Code*, Prentice Hall, 2008](https://www.informit.com/store/clean-code-a-handbook-of-agile-software-craftsmanship-9780132350884).

## Pattern fit

| Pattern | Fits when | Over-engineering when |
|---|---|---|
| [Strategy](https://refactoring.guru/design-patterns/strategy) | several variants of one algorithm are chosen at run time, or a conditional switches between them | there are a couple of variants that rarely change; a function value does the same job without new types |
| [Factory Method / Abstract Factory](https://refactoring.guru/design-patterns/factory-method) | the caller cannot know the concrete type or its dependencies ahead of time, or a [family of related objects](https://refactoring.guru/design-patterns/abstract-factory) must be created together | one concrete type is ever built; constructor injection already supplies it |
| [Builder](https://refactoring.guru/design-patterns/builder) | an object needs many optional parts (a telescoping constructor), or several representations from one construction process | the object has a few required fields; named arguments or an options record do it |
| [Decorator](https://refactoring.guru/design-patterns/decorator) | a cross-cutting behavior (logging, retry, caching, authorization) wraps a contract without the wrapped type knowing | the stack's order matters but is not stated, or the framework's middleware or pipeline already offers the hook |
| [Mediator](https://refactoring.guru/design-patterns/mediator) | many components would otherwise reference each other directly and cannot change or be reused apart | each request has one handler and the mediator only adds a hop; the mediator grows into a god object; a handler dispatches another command, which [architecture-and-design.md](https://github.com/melodic-software/standards/blob/main/conventions/engineering/architecture-and-design.md#command-orchestration-and-consistency-boundaries) forbids |

"Fits when" follows each pattern's applicability on the linked page. "Over-engineering when" follows its listed costs where that page states one; the rest of that column (Factory's constructor injection, Decorator's framework hook, Mediator's single-handler hop) is this catalog's judgment, bounded by the linked bars. Against an in-process mediator library in particular: "everything is done in-process" ([Comartin, "Why use MediatR? 3 reasons why and 1 reason not", 2020](https://codeopinion.com/why-use-mediatr-3-reasons-why-and-1-reason-not/)).

## Related

- When work stops for the owner, the stop rule and factory floor: [claude-code-plugins loop-lane convention](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/loop-lane/README.md#when-work-stops-for-the-owner).
4 changes: 3 additions & 1 deletion docs/standards/reference-dont-duplicate.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,10 @@ A record whose purpose is evidence keeps its dates and origins: a manifest's ado
- Fowler: [What do you mean by "Event-Driven"?](https://martinfowler.com/articles/201701-event-driven.html)
- OASIS DITA 1.3: [Producing different deliverables from a single source](https://docs.oasis-open.org/dita/dita/v1.3/errata02/os/complete/part1-base/archSpec/base/single-sourcing.html)
- Gasparyan, WTD Portland 2022: [Don't shoot yourself in the foot with content reuse](https://www.writethedocs.org/conf/portland/2022/speakers/#speaker-anna-gasparyan-don-t-shoot-yourself-in-the-foot-with-content-reuse-anna-gasparyan)
- Metz, 2016: [The Wrong Abstraction](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction)
- Dodds, 2020: [AHA Programming](https://kentcdodds.com/blog/aha-programming)

Further reading (links only, not load-bearing until a targeted primary-source verify pass): [Metz, *The Wrong Abstraction*](https://sandimetz.com/blog/2016/1/20/the-wrong-abstraction); [Dodds, AHA Programming](https://kentcdodds.com/blog/aha-programming); [Swett, counter-argument to Metz](https://www.codewithjason.com/duplication-cheaper-wrong-abstraction/); [Go proverb, copy a little](https://go-proverbs.github.io/).
Further reading (links only, not load-bearing until a targeted primary-source verify pass): [Swett, counter-argument to Metz](https://www.codewithjason.com/duplication-cheaper-wrong-abstraction/); [Go proverb, copy a little](https://go-proverbs.github.io/).

## Related

Expand Down