This is the main reason. I also find a few other instances where it's useful: * Calling confusing 3rd party APIs - sure, maybe all your code is self-explanator

This is the main reason. I also find a few other instances where it's useful: * Calling confusing 3rd party APIs - sure, maybe all your code is self-explanatory but your code probably has to talk to somebody else's code and theirs won't necessarily be so self explanatory. * Links to wiki pages and tickets. * As a stepping stone to cleaning up technical debt you might want to explain what is going on before refactoring the code into something more self-explanatry. * Adding context to an otherwise contextless module. * If somebody asked a question in a pull request based upon the code (if the reviewer didn't understand, it often needs a bit more explanation).