Post History

Source: https://writers.stackexchange.com/a/42643
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Source: https://writers.stackexchange.com/a/42643
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

# It depends on the context

Code reviews can be done for various reasons and the way to write one it heavily dependent on the purpose. Some of the reasons you might write a code review:

- As part of a Software Quality Process
  - As a formal deliverable to management or customers
  - As quality assurance measure
- As an answer on [Code Review Stack Exchange](https://codereview.stackexchange.com/)
- As an academic assessment or grading of one
- As part of a hiring process for applicant submitted code

There are a bunch more but those are some of the more common ones. The first point are the kind found most commonly in industry. I don't have experience in all of them and I won't pretend to be an expert on writing them. However here is my advice.

## Writing as a formal deliverable

When you are writing a code review as a formal deliverable it is the same as any other report you would write. This should be a version controlled document with formal headers, footers, table of contents, etc... The goal of this kind of review is to prove that best practices have been followed and the product mets company standards. This document will be archived and kept for a long time.

I don't know of any publicly available structure for this kind of document but most companies will have their own format that needs to be followed. In general you are looking for:

- Code formatting
- Error handling
- Quality and number of testcases
- Adherence to best practice or company standards
- Quality of documentation

## Writing as a quality assurance measure

The most common situation for this type of review is on change-requests to a code base. Other developers will review the code to assess if it should be merged into the main branch. I have always conducted these reviews through tools such as Github or Bitbucket. These tools provide line by line comparisons to the existing codebase and allow you to attach comments directly to the code in question.

The style for these reviews is less of a formal review but more similar to a social media post. You can comment on anything you think needs to be changed. _"Why did you do this?"_, _"You missed a `const` here"_, _"Rename this variable to X"_, and _"Please add documentation to this function, I don't understand it"_ are all examples of the kind of comment you would expect in these reviews.

These reviews are transient in nature as the developer can upload fixes to your concerns and also post replies to explain things. It is about ensuring only good code gets merged, not about writing an amazing report.

## Writing for CR.SE

I have no expertise in this area so I will just link to Code Review's help centre on [How to Write a Good Answer](https://codereview.stackexchange.com/help/how-to-answer). The advice there can be summarised to; be insightful, organise your thought, do the best job you can and be polite.

## Writing for academia

Most homework assignments will fall into a very similar category to 'Writing as a formal deliverable' and you should follow the same advice. When conducting a code review as part of a marking exercise you will usually have the 'correct' answer with you. It is likely no one else will ever see this review unless their marks get audited, write it however you like so long as you give a fair assessment.

## Writing as part of a hiring process

This is similar to writing a review as part of a marking process. One key different is that you are specifically looking for skills the developer is strong in and areas where they need work. Your review should attempt to assess the skill level and experience of the applicant. This will be shared with the hiring manager and/or other members of the hiring panel. Keep it professional in case is it ever seen by anyone else.

## General Tips

These tips apply to all types of reviews.

- **Only comment on inconsistent code formatting.** Do not bother with personal style unless you are working on the same codebase and have a style guide. Tabs vs Spaces isn't an argument worth having on every review.
- **Look for bugs, typos and edge cases.** Give detailed comments anytime you find an actual execution problem with the code. Potentially suggest a solution if you can identify it.
- **Back up your critiques with references.** Any time you call out something that is bad practice but functional you should provide a reference to why it isn't optimal. This isn't about your opinion vs theirs so you only want to suggest actual meaningful improvements. These will have articles or guidelines that you can references in your critique.
- **Don't write their code for them.** Sometimes is can be tempting to suggest a complete change just because it is not the way you would have done it. That isn't the purpose of a code review. If there are good reasons to change the approach you should explain them but this is their code. Let them solve the problem their way, point out flaws but don't attempt to solve the problem and explain it to them until their code matches yours.

Original score: 8