[r24y]

One thing that I believe is under-documented in code is _business decisions_. The team arrives at a decision in a meeting or informal discussion, and it leads to some code that might be tough to understand without context. I'll usually add a comment briefly describing the decision, and initial and date it.

Initially I would just link to a wiki page in a comment, but occasionally these links break, so in my experience it's better to include the notes directly.

[Archelaos]

It is often also useful not only to document the decision the team arrives at, but also briefly write down what was decided not to implement and why. This is very helpful when people come in a few weeks later with a "new" idea that has already been discussed, or in onboarding new people to the project.

[tcoff91]

The commit message should contain all the unusual context needed to understand the change. In practice however, most people write terrible commit messages.

[bornfreddy]

It's not just that. Commit messages have a property that they get overwritten. When I refactor some code for performance reasons, I don't want to remove documentation - which is exactly what happens if I make a commit. True, older commit messages are available in the history, but... not conveniently available.

[ParetoOptimal]

Many never even use multi-line commit messages.

[conradfr]

And ideally the id of the ticket associated to the code change.