Over a million developers have joined DZone.

My Most Frequent Code Review Comment

· Agile Zone

Reduce testing time & get feedback faster through automation. Read the Benefits of Parallel Testing, brought to you in partnership with Sauce Labs.

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 Agile Zone is brought to you in partnership with Sauce Labs. Discover how to optimize your DevOps workflows with our cloud-based automated testing infrastructure.

agile,code quality,writing

Published at DZone with permission of Bozhidar Bozhanov, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}