4 ms·
nothing wrong with the tool, the issue is with the comments that exist and those that don't. getFoo() does not need a comment. if it does, (it shouldn't) and
by teknopaul 5y ago
nothing wrong with the tool, the issue is with the comments that exist and those that don't.
getFoo() does not need a comment.
if it does, (it shouldn't) and its JavaScript, JSDoc is a fine format.
if getFoo() does need a comment, consider changing the code so it doesn't.
Code is read much more often than its written: so be concise.
If the docs can be automated by a simple tool, by definition, they were not necessary.
- nomel 5y agoI generally enjoy a brief description of the overlying concept, at the top of each function. I don't care to know how a function is implemented as much as rough details to help me navigate the new/forgotten code space/context. Usually, a quick example of usage, within some relevant context, is enough to push me in the right direction. If I have to read every line of implementation to know wtf is going on, then I'm probably going to have a bad time.
- iudqnolq 5y agoDepending on the context, I might mention if getFoo is expansive, is cached, talks to the network, or can throw.