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):

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 |.

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 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)

"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

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