Skip to content

Instantly share code, notes, and snippets.

@vievehal

vievehal/code_review_in_lab.md Secret

Last active April 26, 2018 23:30
Show Gist options
  • Star 3 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save vievehal/c3fa3ff081afb2d7f0d0bf8a024468ab to your computer and use it in GitHub Desktop.
Save vievehal/c3fa3ff081afb2d7f0d0bf8a024468ab to your computer and use it in GitHub Desktop.
Download ZIP
Here are a few ideas about introducing GitHub-based science review and code review in labs.
Raw
code_review_in_lab.md

Science and code review

Here are a few ideas about introducing GitHub-based science review and code review in labs.

Tips for using github for science review

In projects where there will be no code changes (or maybe no code involved at all -- this works for benchwork-only projects too!) and the scientist wants project review along the way, you can open an Issue. There you can write up a study plan, paste in figures that are motivating the question, and cc/tag people that might be able to provide feedback to their project. Then in the comments, the people they tagged can chime in. Later on, in comments, you (the scientist) can post updated results/figures/tables/questions and continue to get feedback. This creates a dialog about their project, and can be an easy and inclusive way for people to keep up with each other’s work. It also works as a high-level lab notebook of sorts.

In projects where there are code changes, this process can be easier in a Pull Request. This will allow for in-line commenting, and to request reviews from people who can provide feedback.

Tips for happy code review:

For projects that involve writing or changing code, it's good practice to perform code review. All our work will be peer-reviewed in the end, might as well start the peer-reviewing from day one!

Open a PR, describe what you’re trying to do, and cc/tag the people who might be interested. Each PR should be a small bite, the amount of work that someone could reasonably review within a day. Since this is likely part of a much larger project, link out to a broader project description so the reviewer (and Future You looking back at this) can understand where this small bite fits into the bigger picture.

When you’re ready for review, Request Review from the people you’d like. On a lot of teams it works really well to have a culture of 1-day code review, so the review should take less than 20-30min of the reviewer’s time.

Benefits of small bites/short branches approach:

  • Branches don’t get long and unwieldy -- branches can be merged quickly, important for avoiding merge conflicts on collaborative projects
  • Provides more visibility of everyone’s projects to the rest of the group
  • During review cycle, allows the ideas to be fresh in the minds of everyone
  • Feels good to have lots of small wins https://www.nytimes.com/2018/01/22/smarter-living/micro-progress.html
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment