We Need To Talk - February 2025 Meetup

TL;DR Here are the slides and transcript for a talk I gave at a Meetup event.

NOTE: The audience feedback in this talk convinced me to re-order my process. So the slides and the speaker notes for this talk are now outdated!

Tuesday, 18 February, 2025. The first Meetup of a new group called We Need To Talk. Hosted at the Permutive office near the Barbican.

Last night, I gave a presentation on code review as part of We Need To Talk, a new Meetup series focused on open conversations about challenges in the tech industry. The series is organised by Samira Cheurfi, an Android developer, and Emma Pollock, a communications professional. I know Samira from our time working together on Trainline’s mobile team, which is how I had the opportunity to speak at last night's event. To ensure attendees could fully engage in the moment, I promised to make my slides and a full transcript of my talk available online. That way, no one had to worry about scrambling to take notes—though anyone was, of course, welcome to snap photos of the slides if they wanted to. If you'd like me to give this talk at a Meetup you organise or attend, at your office, or remotely over Zoom, feel free to reach out! I'm happy to travel anywhere in London (maybe even further!) to discuss how we can make code reviews a smoother, more productive experience—without the unnecessary friction, antagonism, or misery that too often comes with them.

Slides

Here are the slides as promised, available in three formats—each complete with speaker notes that serve as a transcript:

• Keynote: This file includes all the speaker notes.

CodeReview_TheMissingManual.key

Download KEY • 11.72MB

• PDF: If Keynote isn’t your preferred format, here’s a PDF version with the same speaker notes.

CodeReview_TheMissingManual.key.pdf

Download PDF • 274KB

• PowerPoint: Finally, here’s the PowerPoint version. Please note that I haven’t verified its quality, as I don’t have PowerPoint installed.

CodeReview_TheMissingManual.pptx

Download PPTX • 13.11MB

Feel free to use these slides and speaker notes for your own talks—whether at your organisation or another Meetup. The goal is to improve the software industry by spreading these ideas. I only ask that you credit me for the ideas and effort behind them, and please do share any questions or feedback you receive!

Q&A

Here is a record of the discussion that followed my presentation. (This is not an exact transcript, as I've edited for better readability.)

Question: 

Would it make sense to swap Reconnaissance (Phase 1) with Scout the Terrain (Phase 2)? My concern is that by the time I’ve read the ticket, invested time in understanding the problem, and shifted my focus away from other work, I then check whether the PR is even reviewable—only to find out it’s not. At that point, I’ve already wasted a significant amount of time. Wouldn't it be more efficient to assess reviewability first?

Erin: 

That’s a great point, and after thinking it over, I agree that Scout the Terrain should come first. It comes down to the value equation of code review—where the goal is to maximize the impact while minimizing wasted time and effort.

The input is our time and energy spent reviewing, and the output is things like catching critical bugs early, improving developer experience, maintaining velocity, and ensuring a codebase remains readable and maintainable. Given that, it makes sense to determine as quickly as possible whether a PR is even reviewable—or even whether it’s ready for review (Phase 3)—before investing effort in understanding its details.

So, yes, I recommend swapping these two phases to reflect that efficiency-first approach. I will update the presentation for the next time I give this talk.

---

Audience Member 1:

I kind of disagree with the need for a ticket. I’d rather insist on really good PR descriptions than requiring a ticket, because the PR is closer to the code, while the ticket is in a separate system. You then have to link them, and that can feel like unnecessary overhead. A well-written PR description is often more valuable than a ticket—though, of course, that depends on the situation.

Erin:

Yeah, I can see that. Some tickets are completely useless because they’re written poorly—

Audience Member 1:

And sometimes it’s a waste of time to write a ticket when the change is tiny.

Erin:

That’s true. There are definitely times when—well, it feels—

Audience Member:

Mmmmmm— (Audience laughs)

Erin:

Okay, I’m going to disagree. I like having a paper trail for everything, because I’ve definitely been burned. I’ll be looking at some confusing code and "mining git" to try and figure out the intent behind the code, and if there’s no ticket, I’m just stuck. No clues.

Audience Member 1:

Yeah, but in those cases, I usually rely on a different source—like linking to a Slack conversation that explains the reasoning.

Audience Member 2:

But Slack messages expire, sometimes after just a few months…

Erin:

That’s a really good point. But here’s the thing—putting all the context in a PR description isn’t foolproof either, because if your organization changes tools, you lose all that documentation.

Audience Member 1:

That’s why it’s best to include it in the commit itself.

Erin:

YES.

Audience Member 1:

I think that should be part of the review process—checking the commits themselves--

Erin:

The commit messages? yea--

Audience Member:

Exactly.

Erin:

I try to make my commit history beautiful—like reading a book. But only after I’ve developed the feature. I don’t actually develop like that in real time, because, well, I’m human. But honestly? I can barely get people on board with the basics, so I can’t even dream about enforcing good commit messages yet.

Audience Member:

It’s important, though.

Erin:

(Jokingly) I don’t have the energy!

Audience Member 2:

But if a company squashes commits, then the commit messages disappear anyway, right?

Erin:

The commit messages that were squashed won't be available on that 'main' branch--unless they are all added to the final commit's commit message--but they’d still be visible in the PR on GitHub.

Audience Member 2:

Yeah, but if you’re trying to quickly understand why a change was made, those commit messages can be really hard to find.

Erin:

You mean because they don’t show up in git blame?

Audience Member 2:

Yeah.

(Multiple conversations start happening at once)

Erin:

Usually, there’s a link to the PR in that commit message, though. The one that you can see in git blame.

Audience Member 3:

But PRs don’t last forever—some organizations delete them after a while.

Audience Member 4:

Yeah, it really depends on the organization.

Erin:

I mean… I feel like all of you have much higher standards than what I’m dealing with. I can’t even get people to write tickets or PR descriptions! Takeaway:

This discussion made me realize something important: I’ve been holding myself to the standard of writing meaningful commit messages for a long time—it’s one of the ways I try to make my PRs more reviewable. A lot of PRs are easiest to review commit by commit, so I’ve always structured mine with that in mind.

But until now, it hadn’t even occurred to me to ask others to do the same. Mostly because, as I mentioned, I can already hear the grumbles and complaints.

That said, I’m now convinced that assessing commit messages should be part of code review. Tickets and PR descriptions can get lost when companies switch tools (or just run out of storage), but commit messages stay with the code forever—making them the most reliable source of historical context.

So, thanks to the lovely audience member who brought this up (you know who you are), I think it’s time to start pushing people to be more intentional with their commit messages. You’re absolutely right—this is the best way.

---

More coming soon