Module 5: Applied Design & Code Review

Primary texts: Clean Code, Good Code, Bad Code, Refactoring (Fowler) Selective support: Head First Design Patterns for pattern combinations, Design Patterns (GoF) for vocabulary, OOAD for diagrams, plus external material on code review (Google eng-practices) and architecture decision records

This guide is the primary teacher. You do not need to read the source books front-to-back to complete this module. You do need to become operationally strong at choosing patterns under real pressure, reviewing someone else's code, writing design documents, and making tradeoffs that will not be thrown away next week.

Scope of This Module

This module is not a second tour of pattern names. It is the module where pattern knowledge, refactoring mechanics, and basic OOD start being used together, in front of other engineers, with stakes.

What it covers in depth:

recognizing the design pressure that justifies a pattern instead of applying patterns for taste or fashion
combining multiple patterns (Decorator, Strategy, Factory) cleanly in one feature without pattern salad
the four rules of simple design and how they drive day-to-day judgment
running a structured code review on correctness, clarity, design, and tests
writing specific, evidence-based review comments and receiving feedback without ego damage
writing Architecture Decision Records (ADRs) and small design documents that actually get read
when a picture (sequence diagram, C4 diagram) earns its keep and when it does not
detecting over-engineering and under-engineering by reading the context, not by instinct
designing for testability without forcing the domain into an unnatural shape
reversibility: distinguishing one-way doors from two-way doors in design decisions
reviewable commits, pull-request shape, and automated checks as part of hygiene
long-term stewardship: boy-scout rule, broken windows, and a readable Git history

What it deliberately does not try to finish here:

full systems architecture and distributed-system design (Semester 4+)
enterprise-scale design review governance and architecture review boards
team leadership, hiring, and performance conversations beyond review tone
advanced formal methods for specification

This is an applied, judgment-heavy module. If you can name patterns and refactors but cannot justify a design choice in front of a skeptical reviewer, you are not done.

Before You Start

Answer these closed-book before starting the main path:

When is "use a pattern" actually bad advice?
What should a useful code review comment contain besides an opinion?
What belongs in a one-page design document that does not belong in code comments?
Name one design decision that is a one-way door and one that is a two-way door.
What is the difference between a nit and a substantive review comment?

Diagnostic Interpretation

4-5 solid answers

You are ready for the full path.

2-3 solid answers

Continue, but expect extra time in the review and tradeoffs clusters.

0-1 solid answers

Revisit Modules 1-4 first. This module assumes you can already name smells, apply Fowler moves, and recognize the core patterns.

What This Module Is For

Applied design shows up every time you are asked questions like:

is this code good enough to merge, or does it need another pass?
which pattern, if any, is carrying its weight in this feature?
how do I explain to a teammate why I changed their abstraction?
what should go in the design document so that the next engineer understands the decision?
when is a quick, slightly ugly implementation better than a clean but speculative one?
how do I tell whether this decision is reversible next quarter?

This module builds the professional judgment needed for:

production code review on a team
writing proposals and ADRs for non-trivial features
leading small design discussions without becoming the bottleneck
keeping a codebase livable over months and years

You are learning to ship design, not to recite it.

Concept Map

How To Use This Module

Work in order. The later clusters assume you already have review instincts and ADR habits from the earlier ones.

Cluster 1: Integrating Patterns in Real Systems

Order	Concept	Type	Focus
1	Choosing Patterns as a Response to Design Pressure	PRIMARY	Patterns solve pressure, not aesthetics
2	Combining Patterns: Decorator + Strategy + Factory in One Feature	PRIMARY	Layering patterns without salad
3	Simple Design: The Four Rules	PRIMARY	Pass tests, reveal intent, no duplication, fewest elements

Cluster mastery check: Can you describe the pressure a pattern solves before you name the pattern?

Cluster 2: Code Review as a Design Conversation

Order	Concept	Type	Focus
4	Code Review Rubrics: Correctness, Clarity, Design, Tests	PRIMARY	A structured lens for every review
5	Writing Review Comments: Specific, Constructive, Evidence-Based	PRIMARY	How to leave comments that get acted on
6	Receiving Feedback: Disagreement, Defense, and Growth	SUPPORTING	Separating your code from your identity

Cluster mastery check: Can you leave three useful review comments on a real PR without any of them being "nit" or "rename this"?

Cluster 3: Design Documents and Decision Records

Order	Concept	Type	Focus
7	Architecture Decision Records (ADRs): Format and Purpose	PRIMARY	Recording the why of a decision
8	Design Documents for Small-to-Medium Features	PRIMARY	One-pager that answers what, why, alternatives, risk
9	Sequence Diagrams, C4 Model, and When a Picture Pays for Itself	SUPPORTING	Visual budgets for clarity, not decoration

Cluster mastery check: Can you produce a one-page ADR that a teammate six months from now could understand without you in the room?

Cluster 4: Pragmatic Tradeoffs

Order	Concept	Type	Focus
10	Over-Engineering vs Under-Engineering: Reading the Context	PRIMARY	Why the right answer depends on the situation
11	Designing for Testability without Damaging the Domain	PRIMARY	Seams without leaking test goo into production
12	Reversibility: One-Way vs Two-Way Doors	SUPPORTING	Cost-of-reversal as a first-class design lens

Cluster mastery check: Can you look at a proposal and label each decision as reversible or not, and as under/over/appropriately engineered?

Cluster 5: Review Workflows and Craftsmanship

Order	Concept	Type	Focus
13	Reviewable Commits and Pull-Request Shape	PRIMARY	Making a PR easy to review without punishing anyone
14	Automated Checks as Part of Design Hygiene	SUPPORTING	Lint, format, and tests as the humane minimum
15	Long-Term Code Stewardship: Boy-Scout Rule, Broken Windows, Narrative History	PRIMARY	Keeping the codebase livable for years

Cluster mastery check: Can you look at a commit history and tell a story about the feature, or is it noise?

Then work these practice pages:

Order	Practice path	Focus
1	Pattern Integration Lab	Building one real feature that needs several patterns together
2	Code Review Workshop	Reviewing provided code samples, writing review comments
3	Design Documentation Clinic	Writing an ADR, a mini design doc, and a sequence diagram
4	Code Katas	Short, focused review and refactoring drills

Use Module Quiz after the concept and practice path. Use Reference and Selective Reading and Learning Resources only for targeted reinforcement.

Learning Objectives

By the end of this module you should be able to:

Justify a pattern choice in terms of concrete design pressure, not fashion.
Combine multiple patterns in one feature without creating pattern salad or accidental complexity.
Apply the four rules of simple design to ordinary refactoring decisions.
Run a structured code review using a rubric of correctness, clarity, design, and tests.
Write review comments that are specific, constructive, and evidence-based, and receive feedback without defensiveness.
Write a one-page ADR and a small design document, choosing the right visual aid when one is warranted.
Read context well enough to tell over-engineering from under-engineering and design for testability without deforming the domain.
Distinguish reversible decisions from irreversible ones and shape risk accordingly.
Produce reviewable commits, pull-request descriptions, and a Git history that tells a coherent story.
Use automated checks (lint, format, tests) as background hygiene, not as a substitute for thinking.

Outputs

one pattern-integration feature in a language of your choice that uses at least three patterns together and passes characterization tests
one code-review workshop file with at least 12 written review comments, each labeled correctness/clarity/design/test and nit/substantive
at least 2 ADRs in the standard Context/Decision/Consequences format
one design document for a feature you are building this semester (the semester project is fine)
one sequence diagram or C4 container diagram for a real system you work in
one commit-history rewrite exercise: take a messy branch and reshape it into a narrative history
one mistake log naming at least 10 real judgment errors such as patterned before I had pressure, nitpicked instead of discussing design, ADR with no alternatives, test-only public method, or irreversible decision made in a sprint
one short memo explaining how this module's habits should carry into Semester 4 and beyond

Completion Standard

You have completed Module 5 when all of these are true:

you can explain which pressure a pattern is absorbing before you name the pattern
you can compose several patterns in one feature without accidental duplication
you can review a 300-line PR and produce useful comments across all four rubric dimensions
you can receive a disagreeing review and respond with evidence, not ego
you can write a one-page ADR that a stranger can understand six months from now
you can read a design and tell whether it is over-engineered, under-engineered, or appropriate
you can describe at least three specific testability seams without testifying the production API
you can split work into reviewable commits and write a PR description that saves the reviewer time
you can tell whether a decision is a one-way or two-way door and scope the analysis accordingly

If you can produce these artifacts but cannot defend the choices verbally, the module is not complete.

Reading Policy

Concept pages are the main path.
Book chunks are selective reinforcement, not a second syllabus.
External links (Google eng-practices, ADR repository, Michael Lynch's review series) are small, focused, and validated.
Read only if stuck means try the concept page, write a draft review/ADR, and compare against a rubric first.
Optional deep dive means additional nuance or additional patterns, not required progression.

Suggested Weekly Flow

Day	Work
1	Concepts 1-3 and one pattern-integration sketch
2	Concepts 4-6 and review exercises on one provided sample
3	Concepts 7-9 and one full ADR plus one mini design doc
4	Concepts 10-12 and a tradeoff memo on a real decision
5	Concepts 13-15 and a commit-history rewrite
6	Practice 1 and 2
7	Practice 3 and 4, quiz, mistake-log cleanup

Reference

If you need exact links into the local chunked books, use Reference and Selective Reading.

Rich Learning Pages

Scope of This Module​

Before You Start​

Diagnostic Interpretation​

What This Module Is For​

Concept Map​

How To Use This Module​

Cluster 1: Integrating Patterns in Real Systems​

Cluster 2: Code Review as a Design Conversation​

Cluster 3: Design Documents and Decision Records​

Cluster 4: Pragmatic Tradeoffs​

Cluster 5: Review Workflows and Craftsmanship​

Learning Objectives​

Outputs​

Completion Standard​

Reading Policy​

Suggested Weekly Flow​

Reference​

Rich Learning Pages​