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).

  • wrt alternatives, in my practice, most productive alternative were log messages. Instead of // here, we're reticulating splines I frequently write log.trace("reticulating splines"). Another alternative is unit tests. Instead of commenting // this should be really simple one can create unit test for that
    – gnat
    Sep 12, 2012 at 7:28
  • 3
    "I request more comments." Sep 12, 2012 at 17:19

4 Answers 4


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.

  • Thanks for the mention of "comment-driven development", it seems quite useful here and I didn't read about that yet. Sep 13, 2012 at 5:44
  • +1: I'm a little leery of "comment-driven development" because I firmly agree with your belief that code should be self-documenting; but overall, a very solid answer.
    – Jim G.
    Sep 15, 2012 at 3:11
  • "CDD" is less a set of rules defining how it should be done, and more a way to write a "first draft" in pseudocode or structured English within the IDE, that paves the way for real code later. When the real code is written you can keep or discard comments as you see fit.
    – KeithS
    Sep 18, 2012 at 15:19

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(...) {

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.

  • 2
    "Overall, the quantity (and even the quality and correctness) of comments is a bad indicator of overall code quality" -> I'm not sure there's such a correlation. I've seen lots of very bad code with absolutely no comments. Sep 12, 2012 at 11:57
  • 2
    @Iorancou: I guess bad code comes more often with no comments than good code which is so good that it does not need any comments. But that may be just because there is much more bad code around than good code. Nevertheless I think Peter is right when he says "don't focus primarily on improving comments, focus on code which needs less comments.
    – Doc Brown
    Sep 12, 2012 at 12:14
  • @lorancou I think that it's exactly what he meant. Lots of (or high quality) comments != high quality code is how I interpret that statement. Sep 12, 2012 at 12:14
  • 1
    @DocBrown Sure, I agree with that. Unnecessary comments are evil. But you can have good, robust, optimized, bug-proof code that might be easier to read with a bit of English on top of it. Saying comments = bad code sounds a bit like a doctrine to me. Sep 12, 2012 at 12:26
  • 2
    @lorancou, my point is exactly as Nadir interpreted: amount of comments does not correlate with quality of code neither negatively nor positively. That is, you can find bad code with no comments, bad code with heaps of (utterly useless) comments, and everything in between. My personal belief/preference is that good code should have a moderate amount of comments, most of which is API documentation, not code comments. Sep 12, 2012 at 12:53

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.

  • 2
    +1 for pair reviews - face to face communication is the best method. Sep 12, 2012 at 11:44

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.