Code reviewing comments

I am presently using TFS’s code reviewing tool and IMHO it lacks visualisation of which comments are important and which are not.

So I came up with the idea of prefixing my comments.

PRAISE: Good refactoring, I like how you remove the negation.

FIX: A null check is missing.

SUGGESTION: Split line.

CHECK: Is it the right enum used here?

EXPLAIN: Is this comparison really correct? I guess so but how does it work?

If there are many FIX but only one or a few are critical I prefix the critical once with RED, like RED FIX.
This gives the oppurtunity to “while you already are in the file, do these things too”.

When code reviewing do not forget to give appraisal too


This is what I wrote at Patricia Aas’ show at Dotnetrocks:

I have learned that some don’t like code review because it is a critique of the code written. When failing a code review the task is halted for a rewrite and everyone loses.

I love it because to me it is a discussion about code and the system *we* are building *together*.
The code involved is a talking piece.

I prepend my comments with “PRAISE:”, “FIX:”, “SUGGESTION:”, “EXPLAIN:” and “CHECK:”.

FIX is the only one failing a code review.
Depending on the amount of, and severity, EXPLAIN and CHECK might give a red flag too.
The rest are for discussion; to learn and spread knowledge.

PRAISE is important. Only giving negative critique wears a relation. It might also be a part of the reason some don’t like code reviews. It can be hard to recognise good code as, as with many things, it steps out of the way so one does not reflect upon it. Good naming of a method, remember to remove old usings, good test data, …

SUGGESTION is how *I* would like to write the code. Change if you like, don’t if you don’t. I’d be happy to talk about it but there is no need to involve me in a decision.

EXPLAIN on the other hand requires my input. I don’t understand what you are doing – please explain it to me. If it is easy to explain then I should probably have understood; but if you have a hard time explaining it, then there is a good chance the code is too complex. (I have found a bug this way.)

CHECK is more serious. I am not sure you are doing the right thing and would like for you (or anyone else, including me) to double check it.

Typically there will be quite some SUGGESTION followed by a healthy amount of CHECK and EXPLAIN.

Tags: , ,

One Response to “Code reviewing comments”

  1. Tobias P. says:

    Thanks. I read this article a while ago, but never implemented the suggestions. Today I got a fellow developer to rewrite a line of code, because I forgot to label it PRAISE. From now on I will use these prefixes all the time.

Leave a Reply