3 ms·
> usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Ah - the "repeat the method names with spaces in it" style of docume
by andybak 7y ago
> usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag.
Ah - the "repeat the method names with spaces in it" style of documentation.
This is merely an exaggerated form of a trap that the majority of documentation falls into to some degree - documenting the "what" but neglecting the "why" or "how".
It tells you the bit you can easily work out by intuition, reading the source or using your IDE's features.
And it leaves out the really important parts: "how should I use this method?" and "why would I need to?"
Method based documentation also has problems explaining how API calls are used in concert. Understanding each method in isolation something leaves huge gaps in understanding how they are to be used together.
And no - you can't plug the gaps with lazy video tutorials.
- oefrha 7y ago> Ah - the "repeat the method names with spaces in it" style of documentation. That's usually a symptom of aggressive linters enforcing the rule that every single public method must be documented. Programmers then produce useless "documentation" to shut the linters up. Utter waste of disk space.
- kbenson 7y agoI can see that as possible, and I can also see how it might very negatively impact a documentation drive on accident. One of those things that sounds good, and could be beneficial, but when enacted without strong guidance just ends up combining with culture or human nature to make things worse. E.g. a rule that says there must be documentation, but without standards and enough review to make sure that it's good documentation. Stats show things getting better, but that's because we always drift towards optimizing what we measure, which is not always the same what we actually want.