I’ve always hated comments that fill half the screen with asterisks just to tell you that the function returns a string, I never read those comments.
However, I do read comments that describe why something is done and how it’s done (usually the single line comments in the code); those come in really handy when trying to understand someone else’s code.
But when it comes to writing comments, I don’t write that, rather, I use comments only when writing algorithms in programming contests, I’d think of how the algorithm will do what it does then I’d write each one in a comment, then write the code that corresponds to that comment.
An example would be:
//loop though all the names from n to j - 1
Other than that I can’t imagine why anyone would waste valuable time writing comments when he could be writing code.
Am I right or wrong? Am I missing something? What other good use cases of comments am I not aware of?
If you use something like Doxygen, you can fully document your return types, arguments, etc. and generate a nice “source code manual.” I often do this for clients so that the team that inherits my code isn’t entirely lost (or forced to review every header).
Documentation blocks are often overdone, especially is strongly typed languages. It makes a lot more sense to be verbose with something like Python or PHP than C++ or Java. That said, it’s still nice to do for methods & members that aren’t self explanatory (not named update, for instance).
I’ve been saved many hours of thinking, simply by commenting what I’d want to tell myself if I were reading my code for the first time. More narrative and less observation. Comments should not only help others, but yourself as well… especially if you haven’t touched it in five years. I have some ten year old Perl that I wrote and I still don’t know what it does anymore.
Something very dirty, that I’ve done in PHP & Python, is use reflection to retrieve comment blocks and label elements in the user interface. It’s a use case, albeit nasty.
If using a bug tracker, I’ll also drop the bug ID near my changes, so that I have a reference back to the tracker. This is in addition to a brief description of the change (inline change logs).
I also violate the “only comment why not what” rule when I’m doing something that my colleagues rarely see… or when subtlety is important. For instance: