browsing through some of my code, I see mainly 2 types of comments :
- Title Related
- who wrote what when for who.
- what's this variable do?
- what about these subs?
- Explanatory
- Delve into methodologies :"you may think that &foo() is the way to go, but I (boo) chose to use &bar() because ..."
- Regexps and tricky blocks : "this replaces any space or tab with ", etc.
- Warnings : "this might look like the regexp is terminating, but since it's a multiliner, and in the middle of a \Q block, it really is just a /. The regexp ends on nnn"
I make it a point to review comments and code on Friday afternoons, so my code is pretty well documented.