[eindiran]

This is my experience as well. I have come to keep a sort-of contextual information hierarchy, where the most important information is evident at the top-level and the most detailed information is easily searchable:

The most-important context is used as the body of commit messages; the more-detailed but still very important context goes into comments directly in the source code. Other context (with regard to why certain decisions were made, things that are tradeoffs, why an operating point was chosen, things to be revisited, how data to support this decision was collected, etc goes into the bug report and a dated text file with the commit hashes and bug number, which makes digging it up later significantly easier: just grep your notes for the relevant bug numbers and commit hashes.

Keeping those very detailed text files has saved me more than once, and when I slip up and don't include information it often comes to haunt me later.

[heavenlyblue]

Why not describe your decisions in the code?

[eindiran]

The behavior of your code changes, so comments need to be regularly updated to reflect the current reality.

You do want context there (in the comments), but often greater context (detailed information, that may go out of scope, or not reflect the current implementation of something) should be preserved elsewhere so you know a year from now why you made a decision.

You could keep all the information in the comments and be disciplined about updating them. But when you want to understand something that has changed, you end up needing to remember to go looking in the correct commits for the comments you made at that time. I personally just prefer dated, static notes that won't change and are easy to grep.

[heavenlyblue]

I mean keeping the history of decisions in code.