[thelastnode]

I like to put a summarizing comment in the code for lines that require justification like the ones you mention. That way the discussion happens on GitHub and the conclusion is in the code, where future developers will see it.

[diggan]

A good thing to think when you start adding documentation to the code is "Am I really writing readable and understandable code right now?". If you answer isn't yes without any hesitation, you usually need to refactor so other people can read your code instead of you needing to comment what you do.

[thelastnode]

True, but sometimes there isn't a choice, e.g., working with a clowntown library, poorly designed legacy code, etc.