[hitchstory]

100% agree with most of this, but I think the why can be dug into a little deeper. Under why comments I find they fit into two categories:

1) Why does the code exhibit behavior X? (~80%)

2) Why does the code do X this way? (~20%)

1 is usually a customer facing quirk which should be written down somewhere, but preferably not in the code directly. This stuff fits extremely well in tests which exercise the behavior ("why does a user get an ID before the creation of a ticket?"), in reference docs ("why country appears 3 times in this API schema") or in a glossary (e.g. a quirks section under the "admin user" wiki page). These explanations will get more eyes on them this way, will be more likely to be kept up to date and will be available to non developers.

2 should not be non-existent but should be rare. In practice I find 2s are almost entirely absent from most code bases because to the person writing the code it is obvious.

For 2, because of this, I find it's better to get somebody else to ask why and use answers to the whys on pull requests to write those comments: https://hitchdev.com/approach/communal-commenting/

[drcongo]

The vast majority of my comments are left for future-me, because next time I'm on this code I likely won't recognise past-me or past-me's motivations.

[crznp]

For (1), anything outside of the code is going to be missed in the next code review. Eg:

// ACME-1275 Acme uses desc field to identify references

Perhaps you can use the reference to point to wherever you documented it. I'd rather just keep the ticket reference, which won't change. Who wants to read docs that get into that kind of minutia anyway?

But without any comment, I'm wasting time looking for it, if I even realize that there is something to be looked up.