Project 1 — The Code Comprehension Brief

“Before you change a single line, you must be able to explain what every line already does.”

Chapter: 1 — Reading Code Like Scripture Due: End of Week 1 Submit: A link to your work — an OnlineGDB project URL with your brief in a README.txt-style comment block (or a public GitHub repo) — plus the original program file untouched at Normal/Medium, or refactored at Hard. See Coding 1’s online-coding workflow appendix for the standard submission workflow. Allowed tools: Your eyes, the official Java 17 API docs (docs.oracle.com/en/java/javase/17/docs/api/), pen and paper, this textbook. Not yet allowed: AI assistance of any kind. Phase 1 is AI-off. The point of this project is to prove you can read code yourself. We will turn the AI on for Project 9.

The Setup

A senior engineer’s first day at a new job almost never involves writing code. It involves reading. The new hire is handed a repo, told “this is what we’re working on,” and expected to come back in a week with intelligent questions. They are not expected to ship features. They are expected to demonstrate that they have understood what they were given.

The deliverable from that week is what the industry calls a comprehension brief, an orientation memo, or simply “what I found out.” Different shops call it different things. The shape is the same: a one-to-two page document that answers, in plain prose, what does this code do, what surprised me, and what would I ask the original author?

That is the artifact you are producing this week.

The apologetic frame: what does it mean to read carefully? The church has read its central text carefully for two thousand years — slowly, in community, across translations, in the original language when possible. The discipline of reading code well borrows from that tradition. You will read your assigned program the way a Bible study leader prepares for Sunday: not for content alone, but for the questions the careful reader has after the casual reader has moved on.

Learning Targets

By completing this project, you will demonstrate that you can:

• Read an unfamiliar Java program of moderate length without panicking.
• Identify the role of every class in a small multi-class program.
• Trace the flow of data from input to output through a main method.
• Distinguish “what the code does” from “what the code is supposed to do.”
• Articulate concrete, specific questions a reviewer would have about the code.
• Spot at least two real bugs or fragilities in unfamiliar code.
• (Medium) Propose a refactor in prose without writing the refactor.
• (Hard) Execute a refactor cleanly while preserving behavior under an existing test suite.

If you can do those seven things by Friday, you have earned a Normal completion.

What You Will Receive

The instructor will distribute a starter pack containing:

• StudyGroupTracker.java — a ~200-line Java program (the target — what you are reading). (download StudyGroupTracker.java)
• StudyGroupTrackerTest.java — a small test suite the program passes today (used at Hard tier to verify a refactor preserved behavior; you do not have to run it for Normal/Medium). (download StudyGroupTrackerTest.java)
• README-starter — three or four sentences describing what the program is supposed to do, at the highest level. (Not a spec — that’s Chapter 2’s topic. Just enough framing that you know what the program is for.) (download the starter README)

The starter pack will be available on the course portal at the start of Week 1. If you cannot find it, ask immediately — you cannot start without it.

Coach’s Note — The target program is deliberately imperfect. It has at least two real bugs, at least two questionable design decisions, and at least one place where the original author clearly intended one thing but coded another. Your brief is supposed to find them. If you finish reading and have nothing critical to say, you have not read carefully enough.

Normal Tier

Goal: A one-page comprehension brief (approximately 400-700 words, plus structured sections) on the assigned program.

Required sections

Your brief must contain, in this order, each clearly labeled:

1. Summary — One paragraph. What does this program do? Treat the reader as someone who has the language but has not seen the program. Avoid “this program reads input and produces output” — that’s true of every program. Be specific.

2. Classes — One bullet per class. For each: (a) the class’s name, (b) what state it owns, (c) what it can be asked to do (paraphrasing the public method names is fine), (d) how it relates to the other classes.

3. Data flow through main — A numbered list of the actual sequence of operations main performs from the first line to the last. “Construct X, prompt user for Y, loop until Z, write to System.out,” and so on. Be concrete enough that a reader could re-construct main from your list.

4. Three questions a reviewer would ask — Three questions. Numbered. Each one specific to this program. Not “is the code well-tested?” — actual questions like “should addMember reject duplicate names, or is that the caller’s job?” or “the constructor accepts a negative capacity without complaint — is that intentional?”

5. Two bugs or fragilities you found — Two. Numbered. For each: (a) where in the code the issue is (file + method + approximate line range), (b) what’s wrong, (c) what would happen if the issue were triggered, (d) how you’d fix it (one or two sentences — not the fix itself).

Format

A plain .txt file or a document is fine. Or a top-of-file comment block in your submitted code. The grader will read it either way.

Grading rubric — Normal (out of 100)

A bug that’s just “this could be more elegant” doesn’t count. A real bug is something that produces incorrect output, crashes, or makes the program behave differently than the README-starter says it should.

Medium Tier (+up to 25% extra credit)

Layer the following on top of a complete Normal brief.

M1. Refactoring Proposal

Add a fourth section to your brief called Refactoring Proposal. In prose, not code, describe one concrete change to the program that would make it better — clearer, safer, more testable, or more maintainable.

Your proposal must include:

• The intent. What’s the change in plain English?
• The rationale. Why is this better than the current code? Be specific about the property that improves (readability, robustness, testability, etc.).
• The scope. Which files, classes, and methods would change?
• The risks. What could go wrong with the refactor? What behavior must be preserved?

A good proposal is the size of a small paragraph. Two or three sentences per item. Don’t write a novel.

Examples of good proposals (not for this exact project — illustrative):

• “Extract the input-parsing logic from main into a private static method parseStudent(String line) so that main reads as a sequence of high-level steps. Risks: must preserve the existing handling of empty lines.”
• “Rename process() to recomputeAverages() so the name describes what the method does rather than what kind of thing it is.”

Examples of bad proposals:

• “Use Streams everywhere because Streams are modern.” (No specific benefit. Speculative.)
• “Refactor for clarity.” (Doesn’t describe an actual change.)

M2. Cross-Reference Check

Add a fifth section called Method Call Graph. List every public method in the program and, for each one, the places it is called from. (For a 200-line program this is doable by hand in ten minutes. Use Ctrl+F.)

The point of this rep: noticing methods that are never called (dead code) and methods that are called from many places (highly-coupled).

Hard Tier (+up to 25% additional extra credit)

Hard tier requires Normal + Medium done well.

H1. Execute the Refactor

Take the refactor you proposed in Medium tier M1 and actually do it. Submit the refactored code as a second file (e.g., StudyGroupTracker.refactored.java). The refactored code must:

• Compile cleanly on Java 17.
• Pass every test in the provided StudyGroupTrackerTest.java. Behavior preservation is the bar.
• Preserve the README-starter’s described behavior in cases the tests do not cover (use your judgment).
• Not fix the bugs you identified in your Normal brief. This is critical: the Hard tier is testing your ability to refactor without changing behavior. Fixing a real bug changes behavior. (We will fix bugs in Project 3.)

Add a final section to your brief — Refactor Notes — describing exactly what changed, with before/after snippets of the relevant code (5-10 lines each), and confirming that all tests still pass.

H2. The Stretch Question

Pick one of the three questions you posed in section 4 of your brief — the one you find genuinely interesting — and write a short essay (200-400 words) answering it as best you can from reading the code alone. No speculation. No “the author probably meant…” If the code doesn’t answer the question, that is your answer: “the code does not answer this question, and here is what a reviewer would need to ask the author.”

This rep trains the reading-as-interpretation skill the chapter is built around. It’s also the rep that most resembles real senior engineering: most of your career, you will be reasoning about code whose author is unavailable.

Submission

Submit one URL via the course portal:

• OnlineGDB project link containing the original program file (Normal/Medium) or the refactored file (Hard), with your brief in a top-of-file comment block or a sibling brief.docx. See Coding 1’s online-coding workflow appendix for the workflow.
• GitHub repo link is also acceptable if you’ve already set up Git on your own.

What the linked project must contain

1. The original StudyGroupTracker.java untouched (Normal/Medium) or the refactored version (Hard).
2. brief.docx — your comprehension brief, with all required sections clearly labeled. (Or a top-of-file /* ... */ comment block in the source if you prefer; the grader will accept either.)
3. (Hard only) StudyGroupTracker.refactored.java plus the test file unchanged and passing.

That’s it. The grader will read your brief, glance at the code, and (for Hard) run the test suite.

Hints

• “I don’t know where to start.” Open the file. Read no more than the imports and the class signatures. Write those down first. Don’t try to understand any method body yet. You’ll be surprised how far that gets you. (Chapter §1.6.)

• “Every method looks important.” Start with main. Whatever main calls is what’s load-bearing. Whatever’s never called from main (directly or transitively) might be dead code — flag it.

• “I can’t find any bugs.” Look at every ==. Look at every loop bound. Look at every method that returns a value but whose caller ignores it. Look at every place user input is consumed without validation. At least one of those will produce a bug in a 200-line student program. Usually three.

• “My questions sound dumb.” Good. Write them down anyway. Real reviewers’ questions sound dumb on the way to becoming the bug report nobody else noticed. A question like “what happens if n is zero?” is not dumb — it is exactly the question the author needed someone to ask.

• “How long should this take?” Normal: 2-4 hours total, including the reading. Medium: add 1-2 hours. Hard: add 4-6 hours for the refactor + test run. If you’re past 10 hours, you’re polishing — stop and submit.

What Mastery Looks Like (Beyond the Rubric)

The rubric tells you what to do. Here is what to aim for:

A great brief reads like a colleague’s email. Not a textbook chapter — a colleague’s email. Direct. Specific. No throat-clearing. The reader finishes it and feels like they could now sit down to a code review without having to re-open the file.

A great brief catches a bug the grader hadn’t planted. (There are at least two planted bugs. There are usually one or two more the original author didn’t notice.)

A great brief asks one question so sharp the grader has to think about the answer.

A Hard-tier refactor reads like less code than the original. If your refactor added 30 lines, you didn’t refactor — you elaborated. Refactoring almost always means deleting more than you add, or moving lines so that fewer things become possible from any given point in the file.

You are aiming for the document a senior engineer would write. The shape is more important than the length.

When You’re Done

1. Read your brief out loud, slowly. Listen to it. Does every sentence pull weight?
2. Run the original program (Normal/Medium) or the refactored version (Hard) with at least three different inputs. Confirm behavior matches your description.
3. Check the rubric one more time. Did you hit every line?
4. Submit.
5. Read Chapter 2. We are about to flip the work — from reading code that exists to writing the specification before code exists.

Coach’s Note — Project 1 looks like the easiest project of the semester because there’s no logic to write. It is not the easiest project. It is the hardest one to fake. A brief either shows that you read the code or it shows that you didn’t. The grader knows the difference in the first paragraph. Do not phone this one in.

Welcome back to the gym. The work has changed. The discipline hasn’t. See you on Monday.