From 3f45ac5b9c8a3aebf44f981bfcc6e8642744d6d5 Mon Sep 17 00:00:00 2001 From: "melodic-standards-sync[bot]" <300666570+melodic-standards-sync[bot]@users.noreply.github.com> Date: Tue, 27 Oct 2026 20:26:25 +0000 Subject: [PATCH] chore: sync standards components (6ae9e341875968a2a16ddee152b9420565e06b2c) --- .../pr-check-managed-files-hosted.yml | 1 + docs/standards/README.md | 1 + docs/standards/design-for-change.md | 45 +++++++++++++++++++ docs/standards/reference-dont-duplicate.md | 4 +- 4 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 docs/standards/design-for-change.md diff --git a/.github/workflows/pr-check-managed-files-hosted.yml b/.github/workflows/pr-check-managed-files-hosted.yml index a630964..e49d1fd 100644 --- a/.github/workflows/pr-check-managed-files-hosted.yml +++ b/.github/workflows/pr-check-managed-files-hosted.yml @@ -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 diff --git a/docs/standards/README.md b/docs/standards/README.md index 3435bb2..e9adbab 100644 --- a/docs/standards/README.md +++ b/docs/standards/README.md @@ -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 | diff --git a/docs/standards/design-for-change.md b/docs/standards/design-for-change.md new file mode 100644 index 0000000..a9b4127 --- /dev/null +++ b/docs/standards/design-for-change.md @@ -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): + + +> 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. + + +## 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). diff --git a/docs/standards/reference-dont-duplicate.md b/docs/standards/reference-dont-duplicate.md index c8e2969..690890f 100644 --- a/docs/standards/reference-dont-duplicate.md +++ b/docs/standards/reference-dont-duplicate.md @@ -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