Code review is the part of the job nobody teaches. Bootcamps grade your output. Tutorials show you the finished version. Neither puts a senior engineer in front of your pull request with a red pen and the patience to explain what the pen is for. Here is what that looks like.
The pull request below is invented for this post. It is not from a client project and no apprentice wrote it. It is, however, a faithful composite of the first pull request most people open on a real codebase: it works, and it has five things wrong with it.
The pull request
Ticket: “Show each customer’s open invoices on the customer list.” The change adds a lookup inside the loop that renders the list.
export async function listCustomers(db: Db) {
const customers = await db.customers.findMany();
const result = [];
for (const c of customers) {
const invoices = await db.invoices.findMany({
where: { customerId: c.id, status: "open" },
});
result.push({ ...c, openInvoices: invoices.length });
}
return result;
}It passes the ticket. On the test database with twelve customers it returns in a few milliseconds. Here is the review.
Comment 1: the query inside the loop
Notice the shape of the comment. It names the problem (an N+1 query), explains why it does not show up yet (small test data), states what will happen at real scale, and suggests two acceptable fixes without writing the code for you. A review that just says “N+1” teaches nothing. A review that rewrites your code teaches you to wait for rewrites.
Comment 2: the untyped result
This is the comment juniors most often push back on, because the code works. The point is not this function; it is every function that calls it. Types are a contract with the rest of the codebase, and a junior on a real team is being trusted to keep that contract.
Comment 3: what happens when a query fails
Real code review includes questions that cannot be answered in the editor. Part of what an apprentice learns is which questions belong to the client and how to ask them in one message instead of five.
Comment 4: the name
Comment 5: the test that is missing
What the review is not
- It is not a grade.The pull request goes back with “changes requested” and comes back improved. Nobody is scored on the first attempt.
- It is not a rewrite. The mentor points; the apprentice fixes. That is the only way the lesson sticks.
- It is not personal. One of the standards we hold mentors to is constructive review that does not humiliate anyone. Every comment above is about the code and the caller, never the author.
How this works on a Blacksmith.Works project
Every apprenticeship project includes senior code reviews (three on a Starter project, five on Professional, ten on Enterprise, with more available at €25 each), returned within 48 hours by an engineer with at least five years of production work. The reviews stay on your record. When you sit in an interview and are asked “tell me about a time you got feedback on your code”, you will have a specific answer, with a specific line number.
If you are a senior engineer and this is the kind of review you already write for free on your own team, we pay for it here.