Running code review inside a research group

In most software teams, no change reaches the main branch until someone else has read it. In most research groups, code is written, run and published by one person. The analysis behind a paper may never have been seen by a second pair of eyes until a peer reviewer opens it, if one ever does.

Internal code review fixes that gap early, when changes are cheap. It also has a less obvious benefit: it spreads knowledge. When a student leaves, someone else already understands the pipeline. This post describes a lightweight way to start, sized for a group of a few people with real deadlines.

Why should a research group review code at all?

Because a second reader catches mistakes the author cannot see. Authors read what they meant to write. A reviewer reads what is actually there. Many of the errors described in our post on common errors in research code are obvious to a fresh pair of eyes and invisible to the person who wrote them.

There are other benefits too:

• Shared understanding. At least two people know how each important analysis works.
• Learning. Juniors learn by reading senior code, and seniors pick up new tools from juniors.
• Readiness for publication. Code that has been read by a colleague is easier to share, document and defend when a journal asks for it.

Review is not a guarantee. It reduces risk. That is enough to justify a small amount of time.

It is also worth being clear about what internal review is not. It is not a gate that a senior person uses to approve or block a student's work, and it is not a replacement for peer review of the paper. It is a routine conversation between colleagues about code they all depend on. Framing it that way from the start makes it much easier to get people to take part.

What is the lightest way to start?

The lightest way is pull request review on a shared repository. If your group already uses git and a hosting platform, you have everything you need. If not, start with our guide to version control for researchers.

The basic flow:

1. The author works on a branch and opens a pull request (some platforms call it a merge request) describing what changed and why.
2. A named reviewer reads the change, runs it if needed, and leaves comments.
3. The author responds, revises and asks for another look if the changes are substantial.
4. The reviewer approves, and the author merges.

A short pull request description makes a big difference. It tells the reviewer where to look and what the author is unsure about.

What: adds outlier filter before model fit (src/02_model.py)
Why: methods section says values > 3 SD are excluded; code did not do this
Check: Table 2 sample size changes from 412 to 398, is that expected?
Unsure: whether the filter should apply per site or globally

Keep pull requests small. A reviewer can read a hundred lines carefully. Nobody reads two thousand lines carefully. If a change is large, split it, or walk the reviewer through it in person.

When is pairing better than asynchronous review?

Pairing is better when the code is new, complex or tied to a deadline. Two people sit together, in person or on a call, and one writes while the other reads and asks questions. Review happens as the code is written, so there is nothing to catch up on later.

Pairing works well for:

• The core statistical model or simulation behind a paper.
• Onboarding a new member to an existing pipeline.
• Debugging a result that looks wrong.

It costs two people's time at once, so it does not replace asynchronous review for routine changes. Many groups use both: pairing for the critical parts, pull requests for the rest.

How do you make review a habit and not a favour?

Use a rota. When review depends on asking someone nicely, it gets skipped under pressure, and it lands on the same helpful people every time. A rota makes it part of the job.

• Assign one or two reviewers per week, rotating through the whole group, including the group leader.
• Agree a turnaround, for example two working days. A pull request that waits a week loses context for both sides.
• Pair people across levels. Students reviewing postdoc code is as valuable as the reverse.
• Count review time as real work in planning and in conversations about progress.

Some groups also hold a short monthly session where one person walks through a piece of code to the whole group. It is a good way to share techniques and makes review feel normal.

What should reviewers actually look at?

Reviewers should look first at whether the code does what the analysis claims, and second at whether someone else could understand and run it. Style comes a distant third.

Priority	Questions to ask
Correctness	Does the code match the methods? Are filters, joins and models right? Are units and missing values handled explicitly?
Reproducibility	Are seeds set? Are paths relative? Are new dependencies recorded with versions?
Clarity	Can you follow the logic? Are names meaningful? Is anything surprising explained in a comment?
Checks	Are there assertions or tests for the new logic? Do existing tests still pass?

Our checklist for reviewing research code was written for peer reviewers, but most of its questions apply just as well inside a lab.

Automate what you can. A formatter and a linter settle style questions before a human sees the code. Tests run automatically on each pull request catch regressions without anyone having to remember. This frees the human reviewer to think about the science.

How do you keep the tone right?

Review the code, not the person, and write comments you would be happy to receive. Research groups have steep hierarchies and many people feel unsure about their programming. A harsh review can stop someone sharing code at all.

Some habits that help:

• Ask questions rather than issue verdicts: "What happens here if the column is empty?" invites thought. "This is wrong" invites defence.
• Mark the weight of each comment. Prefixes like blocking, suggestion and question make it clear what must change.
• Say what is good. A line noting a clear function or a useful test is cheap and matters.
• Keep disagreements about taste out of review. If the group cares, agree a convention once and automate it.
• Talk in person when a thread gets long. Five minutes of conversation beats ten rounds of comments.

Group leaders set the tone. When a senior researcher asks for review of their own code and responds well to criticism, everyone else follows.

What if nobody in the group feels qualified?

Start anyway. You do not need to be an expert programmer to ask whether a filter matches the methods section or whether a script runs from a clean clone. Reviewing is itself one of the best ways to learn.

For more support, look outside the group. Many universities have research software engineering teams who can review critical code or run a training session. The Society of Research Software Engineering is a good place to find that community, and the Carpentries run workshops on version control and collaborative coding. Our post on research software engineers explains what they do and how to work with them.

What to do this week

• Agree in a group meeting to try review for one month, on one shared repository.
• Draw up a simple rota and a turnaround target.
• Add a pull request template with four lines: what, why, how to check, what you are unsure about.
• Set up a formatter so style is off the table.
• At the end of the month, spend fifteen minutes on what worked and adjust.

Expect the first few reviews to feel slow and a little awkward. That passes quickly once people see a real bug caught before it reached a figure.

Keep it small enough that nobody resents it. A habit that survives a deadline is worth more than a thorough process that is dropped the first busy week.