Please stop commenting your code
Code is the easy part to understand. Instead, spend your time giving me the broad clues as to how the code base hangs together: the concepts, the intentions, the analogies, your thinking, how you see it being used. And then tell me the gotchas.
How about only writing code comments when there's something newsworthy to say? Or giving me an example, or pointing me at a test if tests are rare? What if we accept that our project and team has conventions, and we kind of get them, so you don't need to cover them off in comments? There would be fewer comments, and those that survive would be more likely to be useful.
The alternative is a nice formatted file with standard or bland comments that will just fade out as background noise---noise which is often (a) pointless and (b) out of date. And possibly the worst of all this, comments that are just taking up space on my screen, and masking actual useful information that might possibly be buried under some "returns a list of users from the database"-style worthless comment.
I'm not saying no to comment. What do you think of this:
For instance, would you rather use a one-liner that requires a 3-line comment, or a 10-liner that requires no comments? In most cases, code's readability suffers more when it's overly verbose than when it has a high comment to code ratio. Thus, I would choose to write the comment in most cases.
via jasonmbaker.com
Only a year ago I had the opposite opinion, but now I'm in total agreement. Plus, if you find a funky or idiomatic one-liner the comment would pass that technique on to the team. But please only do that once: don't copy and paste the comment with the code.
Yes, I've joined the anti-comment bandwaggon.
Yes, I know it's a bit more complicated than that.
