Mike Clark wrote an
interesting piece on comments, and I have a few things to contribute as
well.

Here are some of the practices I follow with regards to comments:

  • I configured Eclipse so that whenever I create a new class, it inserts a
    JavaDoc comment that says "This class ".  Yup, that’s right.  Just
    these two words.

    I found that modifying templates so they contain fragments of sentences
    forces a reaction in me.  As soon as I see them, either I go ahead and
    edit them to complete the sentence, or I delete them completely.  Which
    is much better than seeing five lines of text saying "This comment was
    generated in a template.  To configure your template, go to Windows /
    Preferences /…".
     

  • I like to add comments for closing braces:

      } // for (word in sentence)
    } // if file exists

    I don’t know about you, but to me, a closing brace means nothing.  I
    have no idea what it applies to and while I can obviously put my cursor on
    it and find its matching pair (Ctrl-Shift-p in Eclipse), it’s actually much
    better to write it down explicitly.  This kind of comment helps me
    understand the algorithm I am looking at much better and sometimes, even
    spot bugs right away ("Shouldn’t we close the file outside the for loop?").
     

  • There is a big difference between a JavaDoc comment and a regular
    comment.  This is a point that seems to be absent from Mike’s article
    but it’s a very important one.  For that reason, I find it acceptable
    to be less strict when you are writing a non-JavaDoc comment (you don’t
    really need to supply an @param for each parameter of your method).  I
    also tend to reserve the /* syntax for JavaDoc comments and multiple //
    comments for the rest (this is purely a matter of taste).
     
  • I like to comment blocks of code at a time, as opposed to commenting
    lines.  For example, I will spend two-three lines describing a for loop
    at the top of the said loop but I will probably not bother adding extra
    comments inside (there are exceptions to this rule if the loop is
    particularly complicated, of course).

These are all more or less personal preferences, but there is one rule that
think should be applied at all times:

Get in the habit of commenting code that is not yours.

This is not easy.

There is some kind of unsaid rule in the software development world that
somehow makes it hard for people to follow this rule.  Think about it: 
how would you feel if you see a commit log indicating that someone modified a
file that you created and all they did was adding comments?

Chances are you will take it a bit personally…  "Is she trying to tell
me my code isn’t clean? Or that my comments are not good enough?".

You need to get over it.  There are many reasons why people other than
you adding comments to your code is a Good Thing:

  • Your comments show your own bias.  Since you wrote this code, you
    are making a lot of assumptions on what the reader already knows and you
    will most likely omit details in your comment.
     
  • Consider this a code review.  Code reviews are fairly rare in my
    experience, so any opportunity you can have to get somebody else to take a
    close look at what you wrote and try to actually understand it is a great
    way to improve not only this particular piece of code but your skills as a
    whole.
     
  • Somebody else commenting your code goes a long way toward making your
    code easier to read and evolve in the future.  They are trying to share
    their perspective on what you wrote and make it available to everybody else. 
    They are trying to save future developers the trouble they had to go through
    your code.

So next time it happens, don’t take it personally, take a close look at the
new comments and if they are not to your liking, work with the person to improve
them.  And of course, feel free to return the favor, and if everybody does
their part, your code base will end up being easier to read and maintain.