3 ms·
Is this really valuable documentation? A common advice for documentation is "why not how", I'm not sure you can do "why" by looking at the "how". You can do j
by riffraff 4y ago
Is this really valuable documentation?
A common advice for documentation is "why not how", I'm not sure you can do "why" by looking at the "how".
You can do javadoc style params, and there's some value there,but not much.
- pjerem 4y ago> A common advice for documentation is "why not how", I'm not sure you can do "why" by looking at the "how". You are right. It’s the rule when you write the doc. But when you are let alone in an unknown codebase, having your IDE summarize the "what" in the auto completion popup could be really useful. Especially in codebases with wrong naming conventions.
- scarface74 4y agoFor some AWS automation scripts I wrote, I was able to ask, “why would you use this” and the answer it gave me was impressive.
- Beltalowda 4y ago> A common advice for documentation is "why not how", I'm not sure you can do "why" by looking at the "how". The "why" is important for inline comments, but for function and method comments I think the biggest is neither "why" nor "how", but "what". As in, "what does this method do?" especially with regards to edge cases. I tried a few methods just now; it gives okay-ish docs. Lots of people don't write great comments in the first place, so it's about on-par. Sometimes it got some of those edge cases wrong though; e.g. a "listFiles()" which filters our directories and links isn't documented as such, but then again, many people wouldn't document it properly either.