A code diff can tell you what changed and still leave the most useful question unanswered: why this approach? I find that a brief note written near the work can preserve the constraint and trade-off that would otherwise disappear once attention moves to the next task.
Capture the Constraint
Start with the condition that narrowed the options. Perhaps an existing API must remain unchanged, a screen has to work with partial data, or a new behavior needs to fit the patterns already used elsewhere in the codebase. Naming the constraint gives future readers a way to judge the choice fairly.
Without that context, a practical compromise can look arbitrary—or a deliberate boundary can look like an unfinished feature. One or two sentences are often enough to make the code easier to revisit.
Name the Trade-Off
Most engineering decisions exchange one cost for another. A simpler implementation may leave a rare case for later; a more flexible design may ask the team to maintain extra concepts. Write down what the chosen option improves and what it makes less convenient.
This is not a request to document every line. Focus on decisions whose reasoning is not obvious from the code itself, especially where another reasonable engineer might choose differently.
Leave a Trail for Later
A useful note points toward something concrete: the relevant change, a test that captures the behavior, or the condition that would justify revisiting the decision. That makes it more than a record of past thinking; it becomes a practical aid for the next person touching the code.
I would rather keep a small, accurate trail than write a polished explanation months after the details have blurred. When the reasoning is fresh, record the constraint, the alternative you set aside, and what you learned. The code says what happened; the note helps explain why.