I think of comments similarly to footnotes and embedded notes in prose writing. If there's something I can explain in the normal flow of writing, I do so. If I

I think of comments similarly to footnotes and embedded notes in prose writing. If there's something I can explain in the normal flow of writing, I do so. If I have to refer to some research, a bibliographical reference, some outside documentation about data formats, or some special business rule which impacts the case I make a note. They are for asides, deeper context, and outside references. Don't use footnotes to explain the paragraph. Use them to explain the context in which the paragraph is to be understood. Likewise, use code comments to explain the context for the code. Many of my comments are an example record for some legacy data format. I don't write a comment for every line of the parsing routine. I give the example record and the code. Many are also notes about an RFC or standard, down to the paragraph, and where my implementation ignores some obscurity in that or which way I interpret some ambiguity in it. Why that standard was chosen rather than a competing standard, though, is often more suitable for the developer doc / README rather than in the comments themselves.