Code review

[noamross]

We should add a section on code review. Some quick notes. This is generally a hard to teach have M3 or similar sessions about, but I'm open to how we might go about it.

• Code and modeling projects can generally use code review, both internally in teams and externally

Code review take take several forms:

• Group code walk-throughs, often best as brainstorming sessions or ways to get broader feedback on how to improve
• In-process checks to look for errors and find opportunities to improve clarity, documentation, reproducibility, or efficiency
• Final checks before shipping or publishing

Plan for code review:

• Determine who should review your project code, and at what stages of the project
• Reviewing a large project can be daunting and time-consuming, so it's best to plan for several, more granular reviews of project steps at different phases of the work.
• Give your reviewers a heads-up of when to expect the code and give them plenty of time (generally a week) to do so.

Get your project's code ready for code review:

• Get the code, including all data and dependency files, on GitHub
• Make sure the code is documented via a README, comments in code, and/or text in R Markdown documents that explains the purpose and structure of the project [TODO, what to document?]
• Test that someone else can run the code and get the same outputs on their machine. This is often the subject of a first (usually internal) code review!

Ideally, a large project to be reviewed will:

• Use targets for workflow, and have a diagram of the workflow generated by tar_mermaid in the README
• Have all dependencies defined using renv and/or Dockerfiles, and have installation instructions for other system dependencies
• Include all outputs (figure, compiled Rmd files) in the github repository
• If some steps take a long time to run, have those targets stored on AWS S3 or otherwise available to inspect without running the code.

CC @emmamendelsohn