[m_fayer]

I strongly agree. I try to urge coders to document intent, that’s how I put it.

Sometimes the intent is obvious and doesn’t need explanation, you’re implementing the feature.

But if the intent is not obvious - like compensating for some out of band failure, or responding to some not obvious business need, or putting in something temporary that will be fixed later, then the reader needs to know.

It’s frustrating that so few think about the perspective and needs of the reader or reviewer, not just the machine.

[childintime]

So put in the issue number and call it a day?

[junon]

This requires 1) that everyone has access to the tracker, 2) the link remains active, and 3) people will take the time to visit something else entirely to get context.

Code is a specification for execution. It should include everything needed to fully execute and understand it.

This is why even microchip makers put much of the SPI signal specification into each datasheet despite SPI being a super common protocol. The more your code's comments act as a datasheet, the better longevity it'll have.