Before we start let’s discuss what exactly is a peer review 🤔
Essentially a peer review is when someone, most likely this will be someone working on your project/team, has a look through some code that you have written and provides you comments or feedback on it. This feedback can be on a wide variety of aspects of your code. This can be but is not limited to, anything from code style and accuracy to naming conventions and testing.
It may also be the case that the reviewer will try to run your code and use it as a typical user would assess if it meets the requirements or not. In my experience, this is generally a good step, especially for changes that aren’t simple. This is because it means that the reviewer will have a chance to ensure requirements are met by physically testing and using the changes. Sometimes, code changes may look like they have met the requirements, but until you use the system as a user would how would you know for certain? I know people that approach this step first in a code review even before looking at the code because it means they look at the system as a user might. This could provide useful insights and expose edge cases that might not have been thought through and catered for in the code.
I find that testing your code by using the system as a user would is an essential part of the development process, and helps ensure we are meeting the acceptance criteria on the piece of work we are doing.
Where to start if I’m doing a code review? 🙋♂️
So as mentioned above my recommendation for a good place to start is by cloning the code locally and testing that it meets the requirements. Note down any user experience issues you might find or things you might want to assess further once you delve into the code.
Once you’ve tested the changes by using the system you can now look at the code changes. Sometimes the above step might not be possible for various reasons e.g. system requirements etc, so it is also ok to skip that step if needed.
Before making any specific notes on what could be improved, have a look at the changes as a whole. Make sure you understand what the differences are doing, and how they might affect other parts of the code base. If you can’t seem to work out what is happening and how the changes are working this would be good to clarify with the developer in question. If you are finding it challenging to understand reviewing the code then there is potential that other developers would also find it challenging to understand and changes might be needed to make it more understandable. If no changes are possible then at least a note to add comments in the code might help.
But the preference is that code is self-explanatory, easy to understand, follow and modify without the need for additional inline comments. This is because comments can quickly become outdated and incorrect if not regularly maintained. Additionally, difficult-to-read code is the quickest way to create a code base that is difficult to maintain and modify. That's why when writing your code you should make an effort to think about how your code will be used in the context of the system as a whole and how it may be used and maintained by other developers/yourself in the future.
When reviewing code, it is not your job to tell the other developer what to do and that they messed up, but instead it is to provide feedback and help your colleague write better more maintainable code.
Always suggest improvements and changes without making references to the person in question. For example don't say "You wrote this line incorrectly, it should be like this." Instead try rephrasing it to something like the following: "Line 30 in the controller seems a bit confusing. Do you think there is a better way it could be written?". Phrasing your comments like this facilitates discussion and will allow the other person to think about the work, learn and grow.
Code quality and correctness ✅
After you've looked at the code changes as a whole now it's time to assess the correctness of the changes and the quality of the code that is written. This means checking against the business logic in the requirements provided and for coding mistakes.
For example, this might involve flagging possible null references or missed logging items. This could be flagged by looking at the code and assessing possible edge cases and by doing manual tests on the system where objects passed into the code are empty e.g. submitting an empty form. From a user experience perspective, we must ensure the system handles similar situations gracefully i.e. if data is missing then inform the user using inline errors or warning pop-ups as an example. Unit tests and automated tests are usefully in ensuring these edge cases are covered. In addition to edge cases, I would say that unit tests in general and unit test coverage should also be covered as part of peer reviews. Have unit tests been created, how many lines of code do they test? Tools such as ReSharper can help here. At the very minimum, I would say the most common code paths should be covered. Ensuring code is working correctly with unit tests and automated tests is incredibly important when working on any code base that will be used in production. It ensures that when you make changes you aren't also inadvertently breaking other parts of the system.
Another part of the code review should entail looking at the code structure overall. This might be hard to do when looking at specific code changes if you don't have a lot of awareness of the wider scope of the code base. The best thing to do here is to look at how consistent is the code being reviewed with the existing code. If the code looks significantly different I would start to question why that is.
Final thoughts 👨💻
These are the steps that I take to do a peer review. To recap the steps are:
- General test by testing the system as a user would
- Read and understand the code changes as a whole
- Flag any code quality issues or missing business logic
- Ensure there are adequate unit tests and automated tests
- Assess changes when compared to the current overall structure of the code
Hopefully, you have found this article helpful. If you have any other tips or suggestions that you would do when carrying out a code review then please comment then down below.
Until next time 😀
