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”.
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”.
Hi!
You should definitely take a look at Gitcolony! Gitcolony allows teams to build bulletproof software faster. By streamlining the code review process, automating QA, adding a layer of business rules to code management and incorporating gamification, Gitcolony allows teams to build better software in an efficient and amusing way.
Gitcolony encourages developers to share early feedback, do partial reviews, reduce rework and leverage the knowledge of the whole group. Teams become more efficient by adding visibility to the process.
All the best!
I think the code itself should be self-explanatory. If it isn’t, then the code review should be aimed at getting it there. And, worst case scenario, if you’re browsing some code and you can’t find out why it’s there, I would just check its version control history.
I agree with banyuken. If you were to read Clean Code chapter on comments, one of the points is to make your code so descriptive that you won’t need comments. Comments have tendency to become a smell since a lot of times, they are not maintained and quickly become out of date with the actual code.
The code is descriptive about WHAT it does. It cannot have all the context in it to understand WHY it does it. Hence the need for comments.
Agreed!
This is a very good code review comment.
We should “Plan for humans, not machines.” : http://bravenewgeek.com/writing-good-code/
I’ll riցht awasy takе hold ߋf үour rss as I can’t find yߋur e-mail subscription link ߋr e-newsletter service.
Do уߋu ɦace any? Please allow me knoա so thaat Ӏ
mayy subscribe. Ƭhanks.
Hurrah! Finally I got a web site from where I can genuinely
take valuable facts concerning my study and knowledge.
Thanks for sharing