The gold standard, as so often, is to consult an oracle able to tell you what questions you will be asking when looking at the comment or commit in the future. Then answer those questions and write them down.

In lieu of an oracle, use your experience and best judgement.

Oh and never write whole papers to explain what you're doing, unless you're actually writing a whole paper. Instead, drop a cheeky doi;// URI as the only comment of the whole file to document that you're an experienced enough programmer to copy from papers instead of stack overflow.