Some years ago I thought very high of code comments because they were a mean to explain the obscurities of code and, even more, because Joshua Bloch advised in their favor! Then I start being interested into agile techniques mainly as a mean to gain efficiency and productivity with my team. The agile technique is against comments because they get old, out of sync and nobody that knows the code (agile preaches against code ownership) needs it. There is also the fact that a well written code should be auto explicative. That seemed reasonable but my team didn’t use pair programming and it was really difficult some time to understand what a really fast pacing, fast changing code meant: we had a communication problem and the absence of comments just made it harder.
Now I’m working alone on some projects of my own. I should know my code pretty well and still I feel the need to comment it. At first I just add few brief one line comments in the most controversial points, or maybe some infamous TODOs to remind me to review something later. The real comments come much later when I review my code. I strongly believe that the code should express a semantic and that semantic should never be obscured by technicalities. So adding a comment explaining what a class do and why is often a good hint pointing to problems or improvements (especially when I find it difficult to explain it in plain English). It’s just that time when you think to your code as a speech with a sense and not as a mere blob of syntactically corrected spaghetti. That helped me a lot making my code prettier and very well maintainable, and I have it well described to other people as a bonus!
Of course, unless it is an API I plan to public (in that case comments are part of the job), I refrain from overdoing it and I am perfectly comfortable leaving obvious things free of comments (no need to explain what String getName() does!).
Fillumina's Blog 