nw-code-design-oo

name	nw-code-design-oo
description	OO code-design SSOT — the WHAT-to-design anti-smell catalog (Object Calisthenics, RPP smell taxonomy, effect isolation) shared by the solution architect (design-time) and the crafter (execution-time).

OO Code Design

Design-time anti-smell catalog for object-oriented work. The architect loads this to design smell-free domain types and module boundaries BEFORE DISTILL authors ATs; the crafter loads the same SSOT for the execution mechanics that enforce it. This file is the WHAT-to-design subset — execution mechanics (batch-then-verify, commit gates, build/test protocol, RPP dispatch) stay in nw-quality-framework and nw-refactor.

Object Calisthenics

9 design constraints for clean OO in the hexagonal core (Jeff Bay). Design domain and application types to satisfy these; enforced at GREEN+COMMIT by the crafter.

#	Rule	Design intent	Layer
1	One indentation level per method	Forces decomposition	Domain, Application
2	No else keyword	Guard clauses, early returns	Domain, Application
3	Wrap all primitives and strings	Value objects at boundaries	Domain
4	First-class collections	Domain collection types	Domain
5	One dot per line	Law of Demeter	Domain, Application
6	No abbreviations	Intention-revealing names	All
7	Small entities (<50 LOC classes, <10 LOC methods)	SRP	Domain, Application
8	Max 2 instance variables per class	Promotes decomposition	Domain
9	No getters/setters	Tell, don't ask	Domain, Application

Rule 9 relaxation — getters allowed for: DTOs/response objects at port boundaries, CQRS read models, value objects with computed properties (Money.amount), framework/ORM mapping. Rule 9 applies strictly to domain entities and application services.

Scope — applies inside the hexagon (domain + application). Does NOT apply to adapters, infrastructure, DTOs, or configuration.

RPP Smell Taxonomy

Smell names an architect detects in a design before code is written. Detection is design-time; the refactor execution (cascade planning, batch-then-verify) is crafter-only in nw-refactor. Levels L1 Readability | L2 Complexity | L3 Responsibilities | L4 Abstractions | L5 Design Patterns | L6 SOLID++.

Level	Smell	Design-time implication
L3	Primitive Obsession	Raw int/str carrying domain meaning → introduce a value object
L3	Magic Numbers	Bare literal with hidden semantics → name it (enum / constant / value object)
L3	Tell-Don't-Ask	Caller queries state then decides → move the decision onto the owning object
L3	Feature Envy	Method reaches into another type's data → relocate behavior to that type
L3	God Object	One type owns too many responsibilities → split along bounded responsibilities
L3	Large Class	Class exceeds SRP / Calisthenics size → extract collaborators
L4	Shotgun Surgery	One change forces edits across many sites → consolidate the concept into one home

Design rule: a smell named here at design time must not survive into the design artifact — resolve it in the type/boundary decisions, not at DELIVER.

Effect Isolation

Design components so the bug class "side-effect-free function silently writes" is non-representable, not testable-around. Push contract enforcement up the type hierarchy as far as the language allows. Three levers:

• Functional Core / Imperative Shell (Bernhardt) — business logic in pure functions; effects only at a thin shell. Approximates IO-monad separation in any language.
• Plan-value pattern — dry-run / preview / validate functions return a Plan data value, never silent side effects (dry_run(cfg) -> Plan pure; execute(plan) the only impure call). Makes "preview wrote to disk" structurally impossible.
• Capability injection — pass restricted interfaces (PlanRecorder, SafeFileSystem(root=tmp)) at boundaries, never god-objects (os, Path.home()). Approximates capability typing via DI.

Per component, declare a contract shape: pure-function (return-only), bounded-change (declared mutation set), or unbounded-preservation (must return a Plan, never mutate). A driving port that "only reads" must not expose write methods — split read/write into separate ports.

Declared inputs at the boundary

The OO reading of contract:declared-inputs-not-ambient-reads (SSOT: nw-cross-cutting-invariants — the gate list and the anchor live there, not here). It is Capability injection above restated as a review question, because that pattern is easy to agree with and easy not to apply.

What does this component read that nobody passed it? For every gate the clause lists, decide at the boundary: a constructor parameter, an injected capability, or an explicit override — with the ambient lookup kept as a default the caller may state.

Resolve it where the caller can see it. A gate resolved lazily, at first use deep inside a method, is read outside the window in which the caller — or a test — controls the environment, so even a caller that wanted to declare it cannot.

Test-side mirror: the Algebraic Analysis Before the Scenario mandate (nw-test-design-mandates), its declared-inputs question.

Enumerate the outcomes before choosing the return type

How many outcomes does this operation have — and does its signature carry every one of them? "It returns the value and raises on the bad case" is the wrong answer: that is N-1 outcomes in the type and one in the control flow. If any outcome is not in the return type, put it there — a value the caller branches on, with the illegal combinations unconstructible (enforce in the constructor: only the outcome that carries a payload may carry one, and it always does).

Why this is a design rule, not a style preference: except matches on class identity, so a raised outcome couples the caller to the exact module object the raiser was loaded from. Where the same package is reachable by more than one path — a source tree plus an installed runtime, a harness that adjusts sys.path, a plugin cache — that identity is not guaranteed. The except then fails to match and a handled outcome escapes as a crash, in an environment nobody was testing.

Keep raise for what it is good at: a programming error (a broken precondition, an import-time drift guard) where crashing is the correct outcome and no except is meant to cross a module boundary to catch it.

FP states the canonical form of the same rule — a total function into a sum type (nw-code-design-fp § Railway, "Count the outcomes before you choose the return type"). This is its OO translation.

Empirical anchor, 2026-08-06 (des.cli.phases): CI reported UnknownPhaseName propagating out of _resolve from the line INSIDE its own try, with the matching except on the next line. resolve_phase documented three outcomes, returned two, threw the third. Returning all three closed the failure class without establishing why the module loaded twice — a fix that does not depend on that answer is a design fix rather than a patch.

Cross-cutting invariants (load them — they are not restated here)

Paradigm- and role-independent rules live in ONE shipped home: nw-cross-cutting-invariants. Load it alongside this skill and honour these clauses by id — they are NOT duplicated here:

• data:consumer-known-before-produced — a datum is produced only because a named consumer reads it, and you must name the JOIN KEY it will be related on. No reader, or no key → the datum is unjustified.
• gate:self-explaining-what-why-how — every rejection states WHAT / WHY / HOW.
• gate:design-principles-gdp-1-9 — the canonical gate-design contract.