What would be a good way to request comments?

Question

In the project/team I'm working the frequency of comments is a little low. One reason might be that it is not clear to the long-time devs what lines in the code really needs a comment (each part of the project has quite fixed devs).

To increase this we plan to let team members review the code and check in "requests for comments", which the main dev of that part should replace with useful comments.

• Do you think this could work?
• If "yes": what tags should we use to mark? (e.g. //TODO please comment)
• Can you think of alternatives for this process?

Edit: I appreciate your answers about best practice in commenting and writing code, and I completey agree. But my question targets the cases where refactoring is not an option (not wanting to change working code, not wanting to "accuse" main dev of producing code that needs refactoring,...) - so only more or better comments are an option (at least for this question).

Answer 1

First and foremost, code should be self-documenting. Each line of code should be easy to decipher, and the sum total of those lines of code should be easy to trace through. This generally means that methods and variables should have descriptive yet concise names, operations should be clearly defined, design patterns that encourage smaller, single-purpose methods should be employed, and "hacks", including code reliant on arcane details of the implementation behind the language spec, should be avoided. Given these things, any reasonably-experienced coder should be able to decipher your code without any comments needed.

That said, you will not always be able to do this. Time, resources, technical ability, etc will at some point force you to do something in a way that is unclear or kludgy. To mitigate the murkiness of your code, comments that state what you are doing and why can sometimes be necessary. It can be difficult for a programmer going flat-out, heads-down at an algorithm to realize when they may be necessary, so a code review step is a good idea. Have another developer go over the code, and if they point to something and ask "why", that's a good candidate for some comments.

Another thing I often find useful is "comment-driven development". When you create a new method, write out lines of comments detailing how the method should progress through its designed task. You're basically making notes about what the method should do, even if at this point in your coding you won't actually write any of the code in that method. This can be invaluable in collaborative programming, where an algorithm for something critical or extremely involved was designed on a whiteboard by the team and then given to one or two coders to implement. Then, as you code, the comments detail the task performed in each stage. They can be removed if the operation is plainly obvious, or they can stay if the logic is more complex than the conceptual idea of that code. However, when using this technique, it's important to understand that what you thought you were going to do isn't always what you ended up doing; you have to identify those cases and either update or rewrite the comments.

Answer 2

IMHO lack of comments is not necessarily a bad thing. Most of the time the code can be written to be self-explaining, thus it needs no comments (apart from API documentation). The few exceptions are when the code is intentionally difficult, e.g. it implements a known algorithm, contains performance optimizations etc.

Overall, the quantity (and even the quality and correctness) of comments is a bad indicator of overall code quality. You should rather focus on the full picture: creating (and keeping) clean, readable, maintainable code - of which comments are only a small part.

So if you see a piece of code which you feel is in need of comments, consider refactoring first. Most often the code can be refactored to be easy to read, and this eliminates the need for comments.

E.g. if you see a long method performing some lengthy operation which clearly has several distinct phases / steps, you may feel it necessary to add comments before each phase, like

void SomeLongCalculation(...) {
  // Calculate the foo coefficient
  ...

  // Determine the bar factor
  ...

  // Sum up the blorg values
  ...

  // Calculate the yearly average
  ...

}

whereas you could extract each step into a separate method with a descriptive name instead:

void SomeLongCalculation(...) {
  CalculateFooCoefficient(...);
  DetermineBarFactor(...);
  SumBlorgValues(...);
  CalculateYearlyAverage(...);
}

This makes each step explicit, keeps all the code in your method on the same abstraction level, thus making it clean and easy to read. Moreover, it enables you to unit test each substep in isolation.

Answer 3

Can you think of alternatives for this process?

Yes, I can. When you are going to review a piece of code, do it pairwise - one reviewer and the dev who wrote it, directly sitting in front of the same screen. Instead of adding "request for comments", let the main dev explain what the code does (and why!), and the reviewer directly add a comment with words he understands.

And think about allowing some refactoring during that process - at least, when you have automatic refactoring tools at hand, which give you only a very small risk of destroying something. I am here with Péter Török - small methods with self-describing names and small scope need less comments and are much better than big methods with lots of block-comments.

Answer 4

I think it is a good idea to do that, if the team is big enough and there is enough time. Comments are necessary in code, the question is how it is done. Your team probably has, or is planning on implementing a comprehensive way of commenting. Either way, the right kind of commenting will speed up the development process, combined with the answer by Péter Török.

On my project last semester, the supervisor used gerrit for the code review. This is the same system that is used in the whole department and it functions quite well. He simply reviewed our code and indicated all the parts that needed more comments or improvements. This can be an answer to your last two questions, or you could find a similar system that does this.