8.2 KiB
8.2 KiB
| books | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Source Coverage Matrix
Use this file after selecting a mode and before writing findings. It exists to prevent shallow "book-name citation" reviews.
Review Discipline
- Cite a book only when the observed symptom actually matches that book's principle.
- A threshold crossing is a hint, not a verdict. Check context, intent, and blast radius.
- Look for justified tradeoffs before flagging a smell as debt.
- Prefer concrete architectural or domain consequences over abstract style complaints.
- If two books pull in different directions, state the tradeoff instead of pretending there is no tension.
Frederick Brooks — The Mythical Man-Month
Encoded today
- Change propagation as communication overhead
- Second-System Effect
- Conceptual Integrity
Do not ignore
- Whether the design shows a single coherent idea or competing local optimizations
- Whether cross-team coordination cost is becoming part of feature cost
Do not over-flag
- Large systems are not automatically second systems
- Multi-module designs are acceptable when they preserve conceptual integrity
Steve McConnell — Code Complete
Encoded today
- Routine length, nesting, naming, and magic numbers
- Construction-phase YAGNI checks
- Defensive programming and error-handling discipline (guard clauses, input validation, explicit error paths, assertions for invariants)
Do not ignore
- Whether low-level readability choices compound into operational risk
- Whether missing error handling makes failure modes invisible to maintainers
Do not over-flag
- Small, explicit guard clauses are not cognitive overload
- A long routine may be acceptable when it is linear, well-named, and single-purpose
Martin Fowler — Refactoring
Encoded today
- Long Method, Long Parameter List, Message Chains
- Shotgun Surgery, Divergent Change, Feature Envy, Inappropriate Intimacy
- Duplicate Code, Speculative Generality, Lazy Class, Middle Man, Data Class
- Flag Arguments: boolean parameters that split a function into two behaviors
- Primitive Obsession: domain concepts expressed as raw primitive types instead of value types
Do not ignore
- Whether the code smell is local or systemic
- Whether a refactoring target has a natural home in the model
Do not over-flag
- Temporary duplication during an active extraction is not always debt
- A data-focused structure is acceptable when it is intentionally a DTO or boundary record
Robert C. Martin — Clean Architecture
Encoded today
- DIP, ADP, SDP, SAP, and layering direction
- ISP: fat interfaces that force callers to depend on methods they do not use
- LSP: subclasses that break the behavioral contract of their parent type
- SRP and OCP: classes with multiple reasons to change; modules closed to modification but open to extension via abstraction
Do not ignore
- Policy vs detail boundaries
- Whether dependency arrows preserve replaceability and testability
Do not over-flag
- Composition roots may depend on concrete infrastructure by design
- Thin adapter layers can import both directions when they are explicitly boundary glue
Andrew Hunt & David Thomas — The Pragmatic Programmer
Encoded today
- Orthogonality
- DRY
- Law of Demeter
Do not ignore
- Whether knowledge duplication is really duplicated decision-making
- Whether coupling is accidental or a deliberate local simplification
Do not over-flag
- Similar code in different bounded contexts is not automatically a DRY violation
- Direct object access inside a cohesive aggregate is not always a Demeter problem
Eric Evans — Domain-Driven Design
Encoded today
- Ubiquitous Language
- Bounded Context
- Anemic Domain Model
- Entity vs Value Object: objects with identity and lifecycle vs. objects defined solely by their attributes (Money, Email, Address should be immutable value types, not mutable entities)
- Aggregate Roots: who owns the invariant boundary; cross-aggregate access only through the root
Do not ignore
- Aggregate boundaries, invariant ownership, and anti-corruption layers
- Whether names match the business language used by experts
Do not over-flag
- CRUD-heavy workflows may legitimately use transaction scripts
- Thin entities are acceptable when the domain itself is simple
John Ousterhout — A Philosophy of Software Design
Encoded today
- Deep vs shallow modules
- Strategic vs tactical programming
- Information Leakage: a design decision encoded in more than one module, creating change coupling even when no explicit import exists between the modules
Do not ignore
- Interface complexity relative to hidden complexity
- Whether repeated tactical patches are raising long-term cognitive load
- Whether a "helper" exposes internal design decisions that callers should not know
Do not over-flag
- Internal implementation complexity is fine when the interface stays simple
- A small wrapper is acceptable when it meaningfully absorbs volatility
Titus Winters, Tom Manshreck, Hyrum Wright — Software Engineering at Google
Encoded today
- Hyrum's Law
- Dependency management and upgrade blockage
- Code sustainability: whether code as written can be maintained, migrated, and upgraded over a multi-year horizon without heroic effort
- Backward compatibility: whether API changes preserve existing callers or force coordinated upgrades across the organization
Do not ignore
- De facto APIs created by observable behavior
- The maintenance cost of exposing too much surface area
- Whether the dependency graph will allow independent upgrades over time
Do not over-flag
- A stable public API is not a liability if it is intentionally supported
- Fan-out alone is not disorder when dependency policy is explicit and governed
Gerard Meszaros — xUnit Test Patterns
Encoded today
- Assertion Roulette, Mystery Guest, General Fixture
- Eager Test, Lazy Test, Test Code Duplication, Behavior Verification
- Erratic Test: tests that produce non-deterministic results due to shared state, time dependence, or ordering assumptions between tests
Do not ignore
- Whether test failures are diagnosable
- Whether the suite shape amplifies maintenance cost
Do not over-flag
- Multiple assertions are acceptable when they express one behavior with one failure story
- Shared fixtures are acceptable when every field is relevant to the scenario
Roy Osherove — The Art of Unit Testing
Encoded today
- Test naming discipline
- Test isolation
- Mock usage guidelines
- Completeness of edge-path tests
Do not ignore
- Whether tests verify behavior rather than wiring
- Whether seams are used to simplify tests, or production code is being contorted for testability
Do not over-flag
- A mock is acceptable when the dependency is nondeterministic and the assertion still verifies behavior
- Naming conventions are guidance; clarity is the goal
Michael Feathers — Working Effectively with Legacy Code
Encoded today
- Legacy code as code without tests
- Sensing and Separation
- Seams
- Characterization Tests
Do not ignore
- Whether the team can change a risky area safely today
- Whether the code offers any seam for isolating behavior under change
Do not over-flag
- Untested code is not automatically legacy if it is stable and not under active change
- Characterization tests are most important before modifying unclear existing behavior
Google Engineering — How Google Tests Software
Encoded today
- Change coverage vs line coverage
- Pyramid shape and suite portfolio economics
Do not ignore
- Whether the suite reflects business risk, not just percentages
- Whether expensive tests dominate feedback loops
Do not over-flag
- A non-70:20:10 ratio can be healthy when justified by platform constraints or product risk
- High coverage is useful when paired with meaningful branch and change protection