202304281610-code_reviews
Code reviews can be seen as a form of asynchronous pair programming.
Benefits of code reviews:
- Catch errors
- Ensure readability
- Check standards are met
- Share knowledge among teams
If you want others to review your code, make sure your code meets common standards and is easy to review.
Things to look for in a code review
This list is compiled from various sources with additions of my own:
Is the code clean and modular?
Also see clean code.
- Can I understand the code easily?
- Does it use meaningful names and whitespace?
- Is there duplicated code?
- Can I provide another layer of abstraction?
- Is each function and module necessary?
- Is a function or module too long?
- Rule of thumb: if a module longer than 1000 lines we should have a discussion about whether it's better to refactor.
- Does the code adhere to the single responsibility principle?
- Does the code pass the squint test?
- When using classes, are they open for extension but closed for modification Open-closed principle?
- Does the code actually achieve the requirements of a user story, task, or bug?
Is the code efficient?
- Are there loops or other steps I can vectorize?
- Can I use better data structures to optimize any steps?
- Can I shorten the number of calculations needed for any steps?
- Can I use generators or multiprocessing to optimize any steps?
Is the documentation effective?
- Are inline comments concise and meaningful?
- Is there complex code that's missing documentation?
- Do functions use effective docstrings?
- Is the necessary project documentation provided?
Is the code well tested?
- Does the code have sufficiently high test coverage?
- Do tests check for interesting cases?
- Are the tests readable?
- Can the tests be made more efficient?
Is the logging effective?
- Are log messages clear, concise, and professional?
- Do they include all relevant and useful information?
- Do they use the appropriate logging level?
Security
- Does the code introduce security concerns?
General tips
- Keep track of people requesting you to review
- e.g. search GitHub using
involves:<YOUR USERNAME>.
- e.g. search GitHub using
- Prevent unnecessary discussions on style by agreeing on a coding style beforehand within your team and by using a code linter to enforce it.
- Keep comments objective. You review code, not the person writing code.
- Explain issues and make suggestions to spark constructive debate, rather than making demands
- Provide code examples for your suggestions where possible to make it easier to act on your feedback
- Ask questions if you do not understand code, rather than signing off blindly. It's OK that someone has to explain their rationale to get their code merged, you cannot do your work otherwise. If you accept a code change that is your stamp of approval and you should take responsibility for that.
- PRs can be time-sensitive so accept that it will sometimes interrupt your own work flow in order to not block the work of (many) others.
Tips when submitting a review request
- Always review your own code first
- Before committing, consider a
git diff --staged, e.g. to check if you left unwanted TODOs.
- Before committing, consider a
- Keep your changes small so they are easier to explain and review.
- Write good descriptions: why are you making this change and what have you changed? Include links to tasks, user stories etc. that are solved by the PR.
- Write clear commit messages for logically separate changes (I call this "atomic" changes)
- Respond quickly to feedback because context switches cost energy for everyone involved
- If the code is difficult to review for whatever reason (e.g. the reviewer is not familiar with the system you are working on), offer to do an in-person pair review.
- In the suboptimal case that the reviewer does not have time to review everything, communicate which parts of the PR are crucial and require review. An in-person pair review helps too.