Agreed. I know I am late to the discussion but first time this week I have had a moment to check it...

I comment for these reasons as well:

1) the business has started to do things differently and so the code needs to change; date and *who* requested the change (my main client has 12 partners) as invariably someone questions it later

2) date is also important if new data is starting to be tracked i.e. new column especially. that way I have a reference to when I get asked "when did we start tracking that". I do not use nulls a lot in columns so blank or zero values do not really tell me when we started to do such and such

3) as Tamar pointed out, I put in approaches tried that resulted in dead ends for various reasons; invariably if changing the code, I will probably go down the wrong trail again (humans are creatures of habit) if I was refactoring the code; might as well state up front that that is a dead end to save everyone time

4) there was a very specific reason for the coding (similar to above but usually more extensive notes). I tend to put these at the bottom of the method so I don't have to scroll through them all the time (with a quick reference near the place they apply to). e.g. this decision had to be made because different life insurance companies calculate payment increases differently and my client had to somewhat "harmonize them" for their calculations. This example is the start of a lengthy set of comments. Maybe this discussion should be kept elsewhere but I know no one at the company tracks things like this (and they retire) whereas the comments stay with the code

*** Notes, Research and Discussion on Rounding Payment Escalation ***

* For the type of annuity product that McKellar sells (from various insurance companies), different companies use
* different methods to determine the next year's value of a payment if it is incremented year over year e.g.
* if someone receives a $500.00 payment in the first year and it is escalated by 3% for the second year, the
* second year's payment value would be $515.00.

* The problem of how to round this increased value year after year has come up because different companies do
* their rounding differently from year to year. The differences between the companies are of two types:

5) a "heading" comment for a large block of code just to make finding it easier when scrolling down. Example is from a long bit of code with sections on what is being validated. I start and end with 3 asterisks e.g.

*** Alerting If Any Nag Fields ***

* this one is going to be fine-tuned a bit: we now track if the user has been "nagged" for any needed fields during...

In short, business logic not documented elsewhere, CYA stuff, dead-ends, headers to speed things up and then what Tamar and Greg talked about, comments to give a hint of what is happening next. Overall, I think it is a lot faster to understand some long ago created code than to have to figure out what is going on (other than the trivial stuff).

Albert

>My policy is that any time I have to stop and think about what code to write next, it's time to comment. Also, anything odd or non-standard. (Found a code yesterday in a MySQL SP saying that the way I had written something seemed ugly, but I couldn't come up with another approach. That's an invitation to find a new way.) Also, any changes with dates, so we can trace issues that arise.
>
>Tamar