Learning Resources
This module is populated from the local chunked books in library/raw/semester-03-software-design/books, plus a small set of validated external references for code-review and ADR practice. Use this page as a source map, not as an instruction to read everything.
Source Stack
| Book | Role | How to use it in this module |
|---|---|---|
| Clean Code (Martin) | Primary teaching source | Default escalation for clarity, review rubrics, comments, functions, classes, simple design, and stewardship |
| Good Code, Bad Code (Hansen) | Primary / judgment | Strong for code-quality rubrics, testability, dependency injection, mocks, and defensive design |
| Refactoring (Fowler) | Primary / tradeoffs | When to refactor, YAGNI, two hats, problems with refactoring, commit cadence |
| Head First Design Patterns | Selective support | Pattern combinations (MVC, compound patterns) and "pattern sense" -- when patterns are and are not the answer |
| Design Patterns (GoF) | Reference only | Canonical vocabulary and pattern-selection discussion; do not read cover-to-cover |
| OOAD | Selective support | When a diagram is warranted, which UML diagram to pick, sequence-diagram examples |
External Resources (validated)
All links below were fetched and verified on 2026-04-22.
| Source | What you get | Best use |
|---|---|---|
| Google: Engineering practices -- Code review | A complete, canonical rubric and etiquette guide used by a large engineering org | Primary external reference for Clusters 2 and 5 |
| Google: What to look for in a code review | Expanded rubric | Cluster 2, Concept 04 |
| Google: How to write code review comments | Tone, clarity, explicit-suggest vs nit distinctions | Cluster 2, Concept 05 |
| Google: Handling pushback in code reviews | Both sides of disagreement; useful for the author too | Cluster 2, Concept 06 |
| Google: The CL author's guide | Pre-review discipline from the author's side | Cluster 5, Concept 13 |
| Google: Speed of code reviews | Why prompt review is a team policy | Cluster 5, Concept 14 |
| Michael Lynch: How to do a code review (human side) | Practical guide for kind, effective comments | Cluster 2, Concept 05 |
| adr.github.io -- Architectural Decision Records | ADR organization, templates, background references | Cluster 3, Concept 07 |
| Nygard: Documenting Architecture Decisions (2011) | The post that popularized ADRs; also itself an ADR | Cluster 3, Concept 07 |
| joelparkerhenderson/architecture-decision-record | Templates (short, long, Nygard, MADR) and real-world examples | Cluster 3, Concept 07 |
| c4model.com -- C4 model | The simplest widely-used framework for architecture diagrams | Cluster 3, Concept 09 |
| Conventional Commits v1.0.0 | Commit-message convention used in examples throughout | Cluster 5, Concept 13 and 15 |
Resource Map by Cluster
Cluster 1: Integrating Patterns in Real Systems
| Need | Best local chunk | Why |
|---|---|---|
| recognizing when a pattern is warranted | HFDP: Intro to design patterns | Grounds the "problem first, pattern second" habit |
| "pattern sense" and force-based thinking | HFDP: May the force be with you (part 1) | Most explicit treatment of pattern pressure |
| combining patterns | HFDP: Compound patterns | Best narrative example of layering patterns |
| pattern selection in GoF vocabulary | GoF: 1.7 How to select a design pattern | Short, dense checklist |
| the four rules of simple design | Clean Code: Simple design rules | Canonical statement |
| duplication and emergence | Clean Code: Emergence, no duplication | Applies the rules in a worked example |
Cluster 2: Code Review as a Design Conversation
| Need | Best local chunk | Why |
|---|---|---|
| what clean code even means | Clean Code: What is clean code (part 1) | Foundational vocabulary for review |
| schools of clean-code thought | Clean Code: What is clean code (part 2) | Shows disagreement is normal |
| comments vs names | Clean Code: Comments do not make up for bad code | Supports review comments about unnecessary comments |
| constructive comments | Clean Code: Redundant comments to scary noise | Sharpens what counts as noise |
| quality rubric | Good Code Bad Code: Code Quality | Clean, short rubric framing |
| "it has to work" | Good Code Bad Code: Code should work | Correctness-first bucket |
| contracts between engineers | Good Code Bad Code: Other engineers and code contracts | Feeds receiving-feedback and review-as-conversation |
Cluster 3: Design Documents and Decision Records
| Need | Best local chunk | Why |
|---|---|---|
| thinking about systems as wholes | Clean Code: How would you build a city | Frames "design is about boundaries" |
| cross-cutting concerns in design | Clean Code: Scaling up, cross-cutting concerns | Feeds both ADR-07 and design-doc-08 |
| design-first posture | Good Code Bad Code: How this book is organized | Supports design-doc-08 |
| why diagrams earn (or don't) their keep | OOAD: Choosing the diagrams | Best diagram-selection source |
| which UML to pick | OOAD: Which UML diagrams should we choose | Direct answer for Concept 09 |
| sequence-diagram modelling | OOAD: Sequence diagrams (MVC chapter) | Worked sequence example |
Cluster 4: Pragmatic Tradeoffs
| Need | Best local chunk | Why |
|---|---|---|
| YAGNI vs architecture | Refactoring: YAGNI and the wider process | Canonical over/under-engineering lens |
| two hats and when to refactor | Refactoring: Defining refactoring and two hats | Separates behavior change from shape change |
| when to refactor (part 1) | Refactoring: When should we refactor (part 1) | Opportunistic stewardship |
| when to refactor (part 2) | Refactoring: When should we refactor (part 2) | Planned refactor windows |
| tests as testability enablers | Good Code Bad Code: Make code testable | Cluster 4, Concept 11 anchor |
| DI as a design, not a test trick | Good Code Bad Code: Design with DI in mind | Seams without damaging the domain |
| "visible only for tests" as a smell | Good Code Bad Code: Don't make things visible just for tests | Direct prescription for Concept 11 |
| mocks and stubs gone wrong | Good Code Bad Code: Mocks and stubs can be problematic | Balancing test doubles |
| reversibility via incremental refactor | Clean Code: Successive refinement | Feeds reversibility Concept 12 |
Cluster 5: Review Workflows and Craftsmanship
| Need | Best local chunk | Why |
|---|---|---|
| small, clean, coherent classes | Clean Code: Classes should be small | Supports reviewable PR shape |
| cohesion and small classes | Clean Code: Maintaining cohesion | Supporting |
| fast, independent, repeatable tests | Clean Code: F.I.R.S.T. | Automated-checks hygiene |
| clean tests | Clean Code: Clean tests | Tests as first-class code |
| self-testing code | Refactoring: Value of self-testing code | Feeds Concepts 14 and 15 |
| stewardship attitude | Clean Code: Clean code attitude | Direct support for boy-scout rule |
| "we are authors" | Clean Code: We are authors | Feeds narrative history |
| "why refactor" | Refactoring: Why should we refactor | Feeds broken windows and boy-scout framing |
Primary Concept -> Book Chunk Map
Every primary concept maps to at least one book chunk:
Use Rules
- If you are stuck on whether a pattern is warranted, go to Head First Design Patterns first -- its narrative style teaches pressure-before-pattern.
- If you are stuck on a review comment, go to Google's eng-practices first; the one-page concept page usually covers the need.
- If you are stuck on an ADR, open the
joelparkerhenderson/architecture-decision-recordrepository for templates; write a draft before reading more. - If you are stuck on testability, Good Code, Bad Code is the best short source.
- Open one chunk for one concept gap; do not read a whole chapter by default.
- If rereading is not fixing the problem, stop and attempt the practice artifact (review, ADR, kata) before reading more.
Required review-and-repair evidence
Complete the evidence-based review extension and all AR1–AR6 gates. Reuse its packet in the project; HCI/accessibility work remains separate and required.