What are your “hard rules” about commenting your code?

Question

I have seen the other questions but I am still not satisfied with the way this subject is covered.

I would like to extract a distiled list of things

Answer 1

A really important thing to check for when you are checking header documentation (or whatever you call the block preceding the method declaration) is that directives and caveats are easy to spot.

Directives are any "do" or "don't do" instructions that affect the client: don't call from the UI thread, don't use in performance critical code, call X before Y, release return value after use, etc.

Caveats are anything that could be a nasty surprise: remaining action items, known assumptions and limitations, etc.

When you focus on a method that you are writing and inspecting, you'll see everything. When a programmer is using your method and thirty others in an hour, you can't count on a thorough read. I can send you research data on that if you're interested.