cc-routine-and-class-design

cc-routine-and-class-design

Three checks catch design problems that can't be patched post-hoc (they require architectural change, not a fix):

Check	What
LSP test	Is "A is a B" literally true? If not, the inheritance is wrong
Containment default	If LSP feels like purity theater, use containment — it's fixable; inheritance isn't
Parameter count	Over 7 parameters predicts interface errors — the interface is wrong

A passing test suite does not clear these: code can pass all tests on day 1 and still carry VIOLATION-level design debt that surfaces during later modification.

Shared thresholds (parameters 7±2, inheritance depth, routine length, cohesion spectrum): Read(${CLAUDE_PLUGIN_ROOT}/references/cc-foundations.md).

When NOT to apply

• One-off scripts and automation.
• Prototyping (time-boxed before committing to a design).
• Pure DTOs without behavior (but DTOs with validation/equals/toString are NOT exempt).
• Framework-mandated inheritance (e.g. Android Activity) — but "framework examples use inheritance" is not a mandate.
• Profiled performance-critical inner loops (show the data).
• Test doubles — empty overrides and minimal abstractions are appropriate in test code.

Modes

CHECKER

Execute the design checklists against routines and classes: Read(${CLAUDE_SKILL_DIR}/checklists.md). Output one row per item: | Item | Status | Evidence | Location |.

Severity	Criteria
VIOLATION	Fails a checklist item (e.g. 10+ params); breaks LSP/encapsulation (empty override, protected base data)
WARNING	Near a limit needing justification (8–9 params, 3-level inheritance); a subjective abstraction concern
PASS	Meets or exceeds the requirement

APPLIER

Produce class interface designs, inheritance/containment decisions, routine signatures, and cohesion classifications.

• Default to containment; inherit only if "is-a" is literally true (LSP) [p.133].
• Inheritance depth: target <3, WARNING at 3, VIOLATION at 4+, SEVERE at 6+ [p.143].
• Parameters: 7 maximum, graduated per the table below [p.178].
• Target functional cohesion [p.168].
• Ask "What should this class hide?" to drive the design [p.139].

Parameter thresholds

Count	Status	Action
1–5	PASS	None
6–7	PASS	Minor concern; document if unusual
8–9	WARNING	Justify in review or redesign
10+	VIOLATION	Redesign — parameter object or split responsibilities

Count all parameters including defaulted ones; variadic (*args/...) counts as 1. Ordering convention (order implies data flow): input-only first, input-output second, output-only third.

LSP

If A inherits from B, every place that uses B can substitute A without breaking. Inheritance requires both:

1. Semantic: "A is a B" makes sense to a domain expert (Dog is an Animal — yes; UserSession is a Logger — no).
2. LSP: every method of B works when A is substituted — no empty overrides, no new exceptions the base doesn't throw, no strengthened preconditions.

If either fails, use containment.

Inheritance vs containment decision

• Shares only data → contain a common object.
• Shares only behavior (method signatures) → use an interface/protocol, not inheritance.
• Shares both data and behavior → inherit only if "A is a B" is literally true (LSP); otherwise contain.

FINAL CHECK (after deciding INHERIT, before committing): depth < 3 (definitely < 6)? No empty overrides needed? All base data private (not protected)? If any answer is NO → contain instead.

Functional cohesion

A routine performs one and only one operation. If you need "and" or "then" to name it, it has multiple operations.

• PASS: ValidateUserInput(), CalculateTotalPrice(), SendWelcomeEmail().
• FAIL: ValidateAndSaveUser(), ReadFileThenParseJSON().

"One operation" is at the routine's declared abstraction level: CreateUser() is one operation even though it validates, hashes, and inserts — those are at a lower level.

Cohesion classification (best to worst — stop at the first match)

Type	Definition	Verdict
Functional	One and only one operation	ACCEPT
Sequential	Operations share data step-to-step in required order	ACCEPT w/caution
Communicational	Operations use the same data but are otherwise unrelated	ACCEPT w/caution
Temporal	Combined because done at the same time (startup/shutdown)	ACCEPT if it orchestrates calls; FIX if it does the work directly
Procedural	Ordered by external requirement (UI flow), not logic	REJECT
Logical	A control flag selects one of several unrelated operations	REJECT
Coincidental	No discernible relationship	REDESIGN

"ACCEPT w/caution" = document why this type is acceptable here, review whether functional cohesion is reachable, and add a TODO if it should improve. Caution is permission with accountability, not permission to ignore.

Detecting orchestration (temporal OK): verbs like orchestrates/coordinates/delegates/dispatches/routes suggest orchestration (calls other routines). Verbs like handles/processes/performs/calculates suggest direct work — check the cohesion type and extract the direct work into named routines.

Improving cohesion

Type	Steps
Sequential	Split per operation; have the dependent routine call what it depends on
Communicational	Split into individual routines; reinitialize data near creation; call both from a higher level
Temporal	Make the routine an organizer that calls doers; name at the right abstraction level
Logical	One routine per distinct operation; move shared code lower; package into a class

Pattern-specific guidance

• Builder — evaluate cohesion at the class level; methods returning this are fine; class cohesion = "constructs one type of object".
• Mixin/trait — single focused responsibility, fewer than 3 per class; prefer containment, which makes the relationship explicit.
• Singleton — extra scrutiny: does the state truly need to be global? Would DI be cleaner?
• Event handlers/callbacks — one event type with one response; for async, evaluate the complete operation, not just what runs before await.

Evidence

• High cohesion → fewer faults: 50% fault-free vs 18% [Card et al. 1986, N=450].
• Deep inheritance correlates with more faults [Basili 1996].
• Information hiding reduces faults ~4x [Korson/Vaishnavi 1986].
• High coupling → ~7x errors, ~20x fix cost [Selby 1991].

This is maintenance data, not shipping data: the gap appears during modification, not first commit.

Chain

After	Next
Design verified	Skill(code-foundations:cc-defensive-programming)