Chapter 12 · Reps

Architecture First — Reps

← Back to Chapter 12

Chapter 12 — Reps

Conditioning, not grading. This week’s reps are design exercises. Most ask you to draw a class diagram and write a responsibility list before you write any code. Some have no code at the end at all — that’s deliberate. The skill is the thinking.

Keep your reps-prompts.txt going. Add a reps-designs.docx where you sketch each design exercise.

You need:

  • A way to sketch class diagrams. ASCII works. Pencil and paper is fine. A drawing tool is fine. Save them somehow (photo, screenshot, copy the ASCII into your log).
  • Java 17 + JUnit 5 for the implementation reps.
  • Your AI assistant for one or two reps.

Reps 1–4: Design Before Code

Rep 1 — Class diagram only, no code

Brief: a small contact list. Add contacts (name + phone). Look up by name. List all contacts. Delete by name. Persist to a file.

Without writing any code:

  1. List every responsibility (single-sentence each, in plain English).
  2. Group responsibilities into classes.
  3. For each class, write a one-line description (no “and”!).
  4. Sketch the dependency arrows between classes.
  5. Identify at least one place where an interface would be the right call.

Save the design in reps-designs.docx under “Rep 1.” 15–25 minutes total.

Rep 2 — Critique a one-class monster

Suppose someone hands you this class skeleton (download ContactApp.java — it compiles and runs as-is, smells and all):

public class ContactApp {
    public void run() { ... }
    public void addContact(String name, String phone) { ... }
    public void deleteContact(String name) { ... }
    public Contact findContact(String name) { ... }
    public List<Contact> allContacts() { ... }
    public void save() { ... }
    public void load() { ... }
    public void printMenu() { ... }
    public void handleUserInput() { ... }
    public String formatContact(Contact c) { ... }
    public void parseCommandLine(String[] args) { ... }
}

class Contact {
    public String name;
    public String phone;
}

Find at least three architectural problems. For each, name a fix.

(Hints: “Manager”-style class; public fields on Contact; one class doing UI, persistence, and domain logic; no interfaces.)

Write the critique in reps-designs.docx.

Rep 3 — Split the monster

Take your critique from Rep 2 and produce a better design — multiple classes, each with single responsibility, with at least one interface for persistence. Sketch the diagram and write the responsibility table.

No code. Design only.

Rep 4 — Compare to a real design

Now look at the habit-tracker design in §12.3 of the chapter. How does your Rep 3 design compare? Notable differences:

  • Did you have a Cli separate from App?
  • Did you have a Repository interface?
  • Did you separate Contact (the data) from ContactBook (the collection)?

Note what you’d change in your Rep 3 design after seeing the chapter’s example. Architectural taste develops by comparison.

Reps 5–6: Refactor for Architecture

Rep 5 — Single class → multi-class refactor

Take a single-class program you wrote in Phase 1 (any project’s main class is fine). Without changing its behavior, refactor it into 3+ classes following single-responsibility.

Write a before-after.docx:

  • The “before” responsibilities of the single class.
  • The “after” responsibilities split across multiple classes.
  • The dependency arrows in the after.
  • Tests that pass on both before and after (proving behavior was preserved).

This is the most important rep of the week. Refactoring for architecture is the senior’s instrument of constant improvement. Do it on real code from your past.

Rep 6 — Introduce an interface

Take any class from Rep 5 that has a “concrete dependency” — it news another class directly. Refactor to use an interface instead:

  • Define the interface.
  • Make the existing concrete class implement it.
  • Change the dependent class to receive the interface in its constructor.
  • Write a second, fake implementation of the interface (for testing).
  • Write a test using the fake implementation.

The test should pass without touching real files, network, or other I/O — that is the value of the interface.

Reps 7–8: Prompt for Designed Code

Rep 7 — Architect first, then prompt

Pick a small problem (your choice — a coin sorter, a Bible-verse rotator, a study-streak tracker, whatever excites you in the under-100-lines range).

Spend 20 minutes designing it on paper: classes, responsibilities, signatures, interfaces.

Then prompt your AI for each class, one at a time, using the implement-to-signature template from Chapter 10. Save the prompts and the responses.

Compare:

  • Did the AI honor your architecture?
  • Did the AI try to add things you didn’t design for?
  • For pieces the AI got wrong, was the bug in the implementation or in your spec?

Log your findings.

Rep 8 — “Build me X” — the anti-rep

This rep is the negative example. Send your AI a vague brief: “Build me a small task tracker.” No architecture from you, no spec, just the brief.

Save the response. Look at the architecture it chose:

  • How many classes?
  • Are they single-responsibility?
  • Is there a persistence interface or is it hard-coded?
  • Are there Manager/Util/Helper classes?
  • Where does state live?

Now sketch how you would have architected the same task. Diff. Write one paragraph: “Where is the AI’s architecture worse than mine? Where, if anywhere, is it better? Why?”

This rep is the cost-of-skipping-architecture made concrete.

Reps 9–10: Naming and Boundary Discipline

Rep 9 — Find five bad class names

Look through any open-source Java project (Spring, JUnit, Apache Commons), or through your own past Phase 1 projects, or through the AI outputs from prior projects. Find at least five class names that are bad by §12.10 standards — “Manager,” “Util,” “Helper,” “Service,” or anything else that’s a placeholder for “I haven’t decided what this class is.”

For each, propose a better name. The better name should describe what the class is, not what kind-of-stuff it does.

Examples:

  • UserManager → UserDirectory or Users or UserRepository, depending on which responsibility you decide it really has.
  • StringUtil → split into purposeful classes (Strings for the truly generic stuff, or merge into the classes that actually use the helpers).

This is the rep that builds naming taste fast.

Rep 10 — “Parse at the edges”

Find a piece of code (yours or AI’s) where a String or Map<String, Object> is being passed across multiple method calls in the middle of the system. Trace it: where does the string become typed? Where does it become string again?

If the string is being passed several layers deep before being parsed, that’s a boundary violation. Refactor: parse at the edge, pass typed in the middle, render at the other edge.

Document the before/after in reps-designs.docx.

Reps 11–12: Practice the Two-Pass

Rep 11 — Draft and refine

Pick a small problem (different from Rep 7). Design it in two passes:

  • Pass 1 (20 min, fast): sketch classes, responsibilities, signatures. Don’t agonize. Save as design-draft.docx.
  • Pass 2 (20 min, refine): re-read your draft. Apply each question from §12.7 (“Can I describe this class in one sentence without ‘and’?”, etc.). Make changes. Save as design-refined.docx.

Diff your draft and your refined version. What changed? Why?

If nothing changed, your refine pass wasn’t honest — try again with sharper questions.

Rep 12 — Break It On Purpose

Six architectural mistakes. Apply each, observe, learn:

  1. Skip design entirely. Send a vague brief to the AI, accept the architecture. Live with it for 30 minutes — try to add a small feature. Notice how hard it is.
  2. Make every class an interface. Take your Rep 3 design, define an interface for every class, write the concrete classes too. Notice the file count double. Was every interface valuable?
  3. Pass Map<String, Object> everywhere. Take any small program and refactor every typed parameter to a map. Notice how every method now needs implicit knowledge of “what keys are expected.” This is the cost of avoiding types.
  4. Make a 200-line class. Combine everything from one of your designs into one class. Test it. Now try to change one piece of behavior. Notice the cost.
  5. Tangle dependencies. Make class A know about class B, class B know about class A. Try to test either in isolation. Notice the cost.
  6. Name everything Manager. Rename three classes from any past project to include “Manager” in the name. Notice that nobody (including you) can tell what those classes do anymore.

Each of these is a real failure mode. Make them on purpose, briefly, so you recognize the smell.

Done? One Last Thing.

Open your my-prompts.txt (Chapter 10) and my-review-checklist.txt (Chapter 11). Add a third toolkit file: my-architecture-checklist.txt. Put in it:

  • The 5 design questions from §12.7’s Pass 2.
  • The single-responsibility sentence-test from §12.4.
  • The “parse at the edges” rule from §12.6.
  • The dependency-arrows sketch step.
  • Any 1–2 additional questions you’ve started always asking.

Save it alongside your other toolkit files. Senior toolkit, complete. You will use it for every Phase 2 project from here forward and for the rest of your career.

Up next: Project 12 — Project 12: Design Before You Prompt.