4 ms·
What belongs in comments describing API methods, why belongs everywhere else.
by ithronmellon 5y ago
What belongs in comments describing API methods, why belongs everywhere else.
- pc86 5y agoIf it's impossible to make "what" clear through the code itself.
- gbear605 5y agoIf a method is part of an API that might be used by developers external to your team, they don’t want to be looking through your code to figure out how to use your methods.
- iudqnolq 5y agoWith a public API it's important to distinguish "currently true from reading the code" and "promised to stay true through minor updates". What comments are useful for that
- CodeMage 5y agoThe point on API methods is incredibly important. True, "Why" is the most important kind of comment, but I disagree with the author's critique of the documentation-generating comments and agree with you. Yes, "what" comments are a source of additional developer effort and of possible inconsistencies between code and comments, but good API documentation is worth writing and maintaining. No matter how well you name your method and its arguments, if it's part of the public API and you don't include a comprehensive documentation comment, I'll be forced to dig through your source.