How to write a code review comments
Outline
- Kindness
- Clearly state your reasons
- To give a clear direction after the issue and pointed out that allows developers to make a balance between their own decisions
- Encourage developers to simplify code or add a description, rather than explain why the code is so complicated
courtesy
Usually when you review someone else's code, kindness, respect, provide clear and effective advice for developers it is very important. This method is done only in the comments for the code , rather than developers . You do not necessarily need to have to operate in accordance with the recommended practice, but when you say something negative or controversial comments must be in accordance with specifications. For example:
Error: "Why do you use multiple threads in such obvious it does not need to be complicated by the scene?"
Correct:. "Here concurrent use only increases the complexity of the system I did not find any real performance boost because there is no performance here it is best to use a single thread instead of multiple threads. "
explain the reason
You just find the "right" example, can help developers understand Why you should write down those comments, sometimes you have to do a little more explanation of your purpose, such as best practices for you to follow, or to improve the quality of your code Some suggestions
Provide guidance
Usually repaired change the responsibility of the developer's submission is not the auditor. As a reviewer you should not carry out the detailed design solutions or help developers code.
But this does not mean that the audit should not provide any help, even though you want to point out a reasonable grasp of the problem and provide a balance between direct solutions. Just point out the problem and allow developers to make their own decisions generally able to help them grow, audit behavior also easier. It will usually produce good results, because the developers understand the code and the needs of more than reviewers.
However, sometimes direct instructions, advice, or even code will be more helpful. After all, the purpose of code review is to make submissions is optimal. The second goal is to improve the skills of developers in the future be able to review more quickly.
Accepted explanation
When you ask developers to code for an explanation when you can not understand, usually end up it requires developers to re-write the code more clear . Under Occasionally, add comments in the code is a good reply, if not explain an overly complex code.
Description write-only code review tool in the future for people reading the code is not helpful. This can only be accepted in certain circumstances, for example you are reviewing a less familiar features, developers have tried to explain to you some of the most of the other reviewers have already know.
Next: How to deal with negative feedback in the code review