A pet peeve of mine is documentation that describes how the code works. If I want to know that, I can just read it (perhaps assisted by an IDE or debugger).*
What I need documented is why the code works like that. How is it intended to be used? What quirks and gotchas are there?
*If the code is not readable it needs to be refactored, not documented.
I’ve yet to see any that are of any use.
A pet peeve of mine is documentation that describes how the code works. If I want to know that, I can just read it (perhaps assisted by an IDE or debugger).*
What I need documented is why the code works like that. How is it intended to be used? What quirks and gotchas are there?
*If the code is not readable it needs to be refactored, not documented.