Mike Clark wrote an
interesting piece on comments, and I have a few things to contribute as
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 /
- 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
- 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
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.