249 lines
8.2 KiB
Markdown
249 lines
8.2 KiB
Markdown
---
|
|
books:
|
|
- The Mythical Man-Month
|
|
- Code Complete
|
|
- Refactoring
|
|
- Clean Architecture
|
|
- The Pragmatic Programmer
|
|
- Domain-Driven Design
|
|
- A Philosophy of Software Design
|
|
- Software Engineering at Google
|
|
- xUnit Test Patterns
|
|
- The Art of Unit Testing
|
|
- Working Effectively with Legacy Code
|
|
- How Google Tests Software
|
|
---
|
|
|
|
# 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
|