The most important thing wrt to commenting code is to put yourself in the reader’s shoes. What would that reader need to know that’s not obvious from the code? One useful exercise is to pretend that you’re leaving your job and you’re doing a brain-dump for the (reasonably bright) person who will inherit your code. Your goal is to anticipate every question they ask or suggestion they make, in the form of a comment. If they’re likely to ask what something does or how it works, add a comment. If you add code to fix a specific bug then add a comment; obviously you didn’t recognize the need for that code at first, or else there wouldn’t have been a bug, so the next person probably won’t either unless you comment it. If they’re likely to say “this would be better if xxx” but you already tried xxx, put in a comment that says “we already tried xxx but it didn’t work because…” IMO that last is the single most useful kind of comment because it saves someone from going down a blind alley. BTW, the same “role-playing” approach works really well for specs too.

Another important skill is knowing when not to comment something. If it’s blazingly obvious what something does and how/why it does it, don’t comment it. If there are too many comments, the person reading the code will often decide that reading the comments is a waste of their time and they’ll just start ignoring them. Then they’ll miss the one comment that really does matter. If you must be verbose in your commenting, at least use some sort of visually obvious marker for really important “you’ll break it if you ignore this” kinds of comments, to distinguish them from the less important stuff.

Lastly, don’t be afraid to spice up your comments. Be totally candid about stuff – yours or someone else’s – that you think is brain-dead. Make wisecracks and in-jokes, within the bounds of good taste and brevity. People are more likely to read your comments if they can occasionally get a chuckle out of them. They’re more likely to enjoy working on your code, and speak well of it/you when asked. These are all good things – for you, for them, for your employer or client. Coding can be dreary enough without robotic comments.

original context