# Scientific Code Review

## Rokem's Notes

code review in the scientific context:

1. reducing errata
2. Providing learning opportunities

------------------

> Code review refers to the practice of looking at someone else’s software and offering suggestions for improvement... The case that I mostly have in mind here is the review of code by colleagues and collaborators on research projects, similar to the review of manuscripts, results and presentations that are common in research groups

----------------

### Methodology

Synchronous vs asynchronous:

- Sync: co-located at the time of the review
- line-by-line (or chunk-by-chunk) walk-through of the elements of the code
- Asynch: automated systems (github PR)
- major disadvantage is interpretability of code

#### As the reviewee:

- Keep the goal narrow and specific, e.g. performance bottleneck at line X
- Give good context (DOCUMENTATION)
- Keep the number of lines small (no more than 200) per session
- Send in advance
- Prepare tests
- Formatting standard

#### As the reviewer:

- Read it through:
- Start with the API if applicable
- Treat it like reviewing a paper (intro, methods, results should all be clear)
- Read tests and execute tester code if available
- Ask questions for clarity on intention of code
- Get details:
- Modularity of code first:
- > One of the main contributions you can make as a reviewer is to pull the code author away from the details, to point out the big picture of the code.
- Maths and logic separate
- Performance if necessary
- > Consider the costs and benefits of adopting a new tool when offering advice about how to improve performance
- Formatting is important too
- Minor changes should be stated as such; the better the formatting the easier it will be to read and review
- Be kind
- > remember that the code was written by a person, who expended creative effort into writing the code. Don’t be dismissive, even if this person did things that you consider to be grave mistakes
----------------------------

# PennLINC Comments