My Most Frequent Code Review Comment

The title implies one prerequisite – you must have code reviews for every piece of code written. For that, FogCreek recently published a list of best practices for code reviews. I will expand on one of the points:

Do comments exist and describe the intent of the code?

This is, in my experience, the problem I’m making review comments about most often. The code itself is good, well-written, tested, follows style guides, handles edge cases, and everything, but sometimes it lacks a description that would be useful to someone who is looking at a given method for the first time in months. So I often add something like:

Could you add a comment describing the intent of this code?

I’ve actually written about that before, and it’s common knowledge that you should add a comment “why” this code is there (rather than what it’s doing). And yet, even my own code sometimes lacks sufficient intent-describing comments.

That’s most probably because when writing the code, the intent is obvious to you. Only if some logic gets rather convoluted, you realize that it would be hard to figure out later. But normally, you consider your code straightforward (and you disagree with yourself when you look at that code in half a year). To correct that, you must make a self-code review after you are done, and ask the same questions that a reviewer would ask.

But whether it’s a preliminary self-code review or the actual one, it seems that the code review is the ideal moment to remind ourselves about adding comments describing why a given piece of code is there and what purpose in the big picture does it serve. So don’t spare review comments like “please add a description about the intent of this piece of code”.