[TO EDIT] reproducible-research/reviewing

[llewelld]

Summary

Code review can be a challenging experience for many developers, fraught with difficulties given that it can feel like a channel for criticism. It can be especially challenging for developers more used to working on individual or less collaborative projects.

The sections on the Code Review Process therefore provides an excellent and essential resource for anyone handling code. I believe there may be scope to add some additional material to try to make the process smoother for people just starting with code review.

The section on Recommendations and Best Practice in particular already goes a long way towards helping address some of these issues. However it might be worth expanding more on the dynamics of code review. In particular, I'd love to see some of the following tackled there:

1. Power dynamics in code review.
2. How to ensure a code review loop concludes.
3. The importance of highlighting where things have been done well.
4. What to do if things become heated.

These are all aspects I've personally found challenging myself in the past.

What needs to be done?

1. Review the existing material.
2. See whether there's scope to add additional material for helping the review process less confrontational.
3. Consider issues around power dynamics.
4. Consider issues around how to ensure a review cycle concludes.
5. Consider ways to emphasise the need to highlight positive aspects during a review.
6. Create a PR to capture any changes.

Who can help?

1. According to the git logs the existing material was created by a number of different authors, including @SarahAlidoost, @sgibson91 and @c-martinez.
2. Anyone with an interest in code review.

Updates

• First set of edits to chapter/subchapter
• Proofread
• Request reviews
• Address reviews
• Merge to main branch

[EstherPlomp]

I recently read a nice publication where the summary and figure 3 could be used as an example: Implementing code review in the scientific workflow: Insights from ecology and evolutionary biology.

I don't think it goes in super deep into the points that you wanted to tackle, but I figured I would drop the resource here rather than opening up a separate issue for it :)

[llewelld]

Thank you @EstherPlomp, that looks like an excellent resource; really great.

Nasir Eisty and Jeff Carver from the University of Alabama are conducting a study to understand the practices, impacts, and barriers of code review techniques for RSEs, which sounds relevant. I asked them if they had suggestions for good reference material and they shared the following, which also look like they could be very useful for this:

1. https://github.com/mgreiler/awesome-code-review-research
2. https://link.springer.com/article/10.1007/s10664-021-10053-x

[EstherPlomp]

Nice! I'll have a look at that as well!

[kallewesterling]

I was part of helping this group get started, which might be helpful too: https://dhcodereview.github.io/ [see our poster here: https://zenodo.org/records/7935109]

[EstherPlomp]

Thanks for sharing!

There's also the code review process by the tidy data team: https://code-review.tidyverse.org/
And a webinar: Tips on how to review your code | Prof Lisa Debruine

[c-martinez]

I've shared this issue with colleagues at the eScience Center, who are more experienced than me on code reviews. We will organise an internal hands-on session in one of our special interest groups to contribute to this chapter.