Re:Should I Comment My Code? The Case Against Code Comments
by crdoconnor on Thursday October 06, 2016 @09:08AM
(#12652089)
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).
* 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).