Peer Code Review | Phase 2: Reconnaissance

Intended Audience: software developers

TL;DR The second phase of code review, reconnaissance, focuses on understanding the problem, gathering context, and ensuring basic functionality.

Photo by evelynn mi on Unsplash

In my experience, the most important phase of a code review is reconnaissance. This is where you lay the groundwork by fully understanding the problem, familiarising yourself with the provided context, and ensuring the code works at a basic level before diving deeper. Skipping this step risks confusion, wasted time, and miscommunication—not just for you, but for your whole team.

In this post, I’ll share how I approach this foundational phase and why it’s essential for setting the stage for a thorough and efficient review. Whether you’re new to code reviews or looking to refine your process, I hope these insights will help you approach your next review with confidence. 

Step 1: Read the Ticket

A clear problem definition is essential for effective PR (pull request) review. You cannot evaluate a developer’s solution without understanding the problem it aims to solve. That process begins with the ticket. I read the ticket thoroughly, ensuring I understand every word and nuance. If anything is unclear to me, I seek clarity—starting with the code author.

If the code author’s response doesn’t fully address my question, I find the person best equipped to provide the answer—whether that’s the ticket’s author, the team lead, the product owner, the designer, or the business analyst—whoever is the “source of truth” on the issue.

This level of diligence might sound excessive, but I assure you, it’s never a waste of time. Misunderstandings about the problem being solved are often the biggest causes of wasted time in software development.

And I don’t stop at the main ticket description! I read through any comment history on the ticket as well. Tickets often evolve through discussions, and important details can be tucked away in those threads. I also make sure to inspect any attached resources, like designs or documentation, to get the full picture.

By taking time to fully understand the problem now, I set myself up for an effective and efficient code review.

What if there is no ticket?

Ideally, every PR should be tied to a ticket. The ticket defines the problem the PR is solving, providing the objective criteria against which I (the reviewer) will assess the code. (Feedback should always be based on objective criteria--I will discuss this in a future post.) Without a clear problem definition, effective code review becomes much harder.

That said, what if there’s no ticket? When this happens, my first step is to ask the author to create a ticket. Since they’re already familiar with the issue, it should be a quick task.

However, this can get tricky. Not everyone loves “process.” Some developers view tickets as unnecessary overhead. Other developers might simply be difficult to approach—especially if they’re more senior. To navigate this, I suggest starting with a polite, neutral request:

Hi Bob! I was just about to start reviewing your PR, but I noticed there isn’t a corresponding ticket. I usually like to read the ticket first—it helps me understand the problem your PR is solving. Would you mind creating one?

If Bob responds positively—great! Problem solved. But if Bob pushes back with something like:

You don’t need a ticket. The PR is self-explanatory. I’m just adding a new screen. It’s really not a big deal.

Now you’re in a sticky situation. You want to ensure the PR has proper context but also maintain a good working relationship. Here’s what you shouldn’t do: write the ticket for Bob. This sets a bad precedent and shifts the responsibility onto you indefinitely.

If there’s no team policy requiring tickets for PRs, you’re in an awkward grey area. Personal preference isn’t enough to enforce a standard. Instead, try framing the request in terms of long-term benefits:

I get what you’re saying—writing a ticket can feel like extra admin, especially after you’ve already created the PR. But a ticket is a valuable reference point for the team. It’s a source of truth that saves time in the long run.

If that doesn’t resonate with Bob, it’s time to let it go. Don’t waste your energy trying to win them over in one conversation. Sometimes, it takes a few missteps for the value of a ticket to become apparent.

You might consider suggesting a policy to your team. Even if not everyone agrees, sharing your perspective ensures the gap in the process is acknowledged. Then, step back. Let the system show its cracks. If issues arise, others will (hopefully) see the need for change.

And remember: don’t play hero. It’s not your job to patch systemic problems solo, and chances are, you’re not being paid enough to take that on.

Step 2: Read the PR Description

After familiarising myself with the ticket, the next step is to read the PR description. If the author has taken time to include notes, it’s worth my attention—they often provide valuable insight into the problem and the solution.

A good PR description might outline key details, such as:

• How the solution was implemented.

• Any trade-offs or alternatives considered.

• Specific areas the author would like feedback on.

These notes can save time and guide your review by highlighting what to focus on. If the description is empty or sparse, you may need to ask clarifying questions during review, but a well-written description can help avoid unnecessary back-and-forth.

What if there is no description?

No PR description? In that case, the code had better speak for itself! But unless the PR is incredibly simple, this isn’t realistic.

There are usually multiple ways to solve a problem. Without a description, we’re left guessing:

• What implementations did the author consider?

• Why did they choose the approach they went with?

• Were there trade-offs or alternatives they evaluated?

For bug fixes, the stakes are even higher. We need to understand:

• What was the root cause of the bug?

• How did the author uncover it?

• Was the solution straightforward, or were there complications?

• If the fix was simple, how do we prevent similar issues in the future?

Sometimes a bug fix might be speculative—adding logging or a “guess fix” for an elusive bug. In those cases, the PR description should outline the monitoring plan. Who’s responsible for following up? What metrics will we track, and how do we decide when it’s time for further action?

A good PR description answers these questions and saves everyone time. Without it, reviewers are forced to ask these questions during the review process, leading to more back-and-forth and delays.

If there’s no description, the best I can do is add my questions to the PR and ask the author to update the description for documentation purposes. If they’re unwilling to update the description and only respond in comments, that’s better than nothing—but far from ideal for the next developer who encounters a problem with that code.

Like ticket-writing, improving PR descriptions is often a cultural shift. Policies can help, but lasting change usually comes from leadership. A manager addressing the issue in one-to-ones and encouraging the team to see PR descriptions as a time-saving tool is far more effective than relying solely on peer pressure or ad-hoc requests.

Step 3: Mini QA

Yes, you read that right! Before diving into a detailed review, I like to run the code and confirm it works at a basic level. This isn’t an exhaustive QA process—I’m not testing every edge case yet. I’m just checking whether the happy path works.

Why? Because if the code doesn’t function on a fundamental level, there’s no point in reviewing it. Who knows how much will need to change to make it work? The best-case scenario is that only one line of code will change. But in the worst-case scenario, all of the code must be scrapped and rewritten.

Reviewing code that’s bound to change is usually not the best use of time. I prefer to send it back. Sending it back without a detailed review reinforces an important cultural message: sloppy, half-baked work isn’t acceptable for review. This shows that you value your time, which in turn also teaches your colleagues to respect your time—and to hold themselves to a higher standard.

You don’t need to be harsh, but avoid coddling. Don’t soften the feedback with “It’s okay, we all make mistakes.” Instead, keep your response factual and concise, like reporting a bug. Include:

1. The exact conditions under which you ran the code.

2. What you expected to happen.

3. What actually happened.

   
   

This gives the author all the information they need to reproduce your experience. It’s not your job to solve the issue—that’s their responsibility. If they need your help, they can ask for it.

What if the code author never ran the code?

If the code doesn’t work, you have to wonder: Did the author run it before submitting it for review? If not, how did they know it worked? What made them think they were done?

Hopefully, the issue is something more reasonable—like different conditions between your setups (e.g., form factors, dependency versions, or browsers). In that case, the author simply needs to broaden their testing.

But if they never ran the code at all, that’s a serious problem. What they are doing cannot be called “software development” by any stretch of the imagination. Someone needs to have a candid conversation with this individual about their development process and the expectations of their role.

Conclusion

The second phase of code review, reconnaissance, sets the foundation for an effective and efficient process. By thoroughly understanding the problem, reviewing the PR description, and ensuring the code works on a basic level, you position yourself—and your team—for success.

This phase isn’t about finding bugs; it’s about fostering clear communication, setting expectations, and reinforcing a culture of quality. Taking the time to establish context and address gaps early prevents wasted effort and builds a stronger, more collaborative development environment.

In the next phases, we’ll dive deeper into the code itself, but remember: effective code review starts long before you write your first comment. Happy reviewing!