Comments


If only people spent as much time writing comments as they did speaking to the evils of comments.  Everything from useless, inaccurate, to many comments make code unreadable, you should code better … etc. 

I haven’t ever looked at a piece of code and thought "wow, way too many comments" or "that code would be beautiful if it weren’t for the comments."

Do the next guy a favor, comment your code. 

Comments (7)

  1. int19h says:

    > Do the next guy a favor, comment your code.

    I’m usually glad to, but, for example, at one place I’ve worked in the path, we had an _official_ policy of "no verbose comments" (because "they contaminate the code and make it harder to read"), which was enforced to the point that, effectively, no comments were written at all – because that way you’d be sure to pass the code check, whereas even a single line of comments could be said to be "unnecessary", because "the code is self-documenting".

    I wish I were kidding…

  2. jaredpar says:

    @int19h

    Only one word to describe that bad situation: wow 🙁

  3. Kris Krause says:

    I hear ya.  However, unit tests are pretty good "comments" too.

  4. Koush says:

    I can think of a time when comments are superfluous and just plain pointless:

    I was asked to comment the functionality of PInvokes into standard Windows functions (such as GetWindowText, CreateEvent, etc) a month ago. What’s even worse is that I used your PInvoke Utility to mass import a bunch of them. My reaction: "… so, have you heard of MSDN or Google?"

  5. jaredpar says:

    @Koush,

    The PInvoke tool comments are as verbose as possible.  Mainly because I wrote it as a tool to help people understand the issues involved with PInvoke.  Giving a full type history hit this band.  

    At the same time it’s generated code so turning off comments is easy.  I’ve gotten several requests to add the MSDN information for the particular function.  I’m definately looking at doing that.  

  6. Svend Tofte says:

    Plenty of comments have led me astray, causing me to waste time trying to merge the text laid out in the comment and what the actual code seemed to be doing, only to find out the comment is wrong, formulated in a way that seems confusing, or using vague terminology I don’t get.

    Comment = more stuff to keep up to date, and there’s no compiler aiding you, to keep the text in check with the code.