3 ms·
Not who you're asking but... why have documentation at all? So that we don't have to read source code.
by staticassertion 5y ago
Not who you're asking but... why have documentation at all? So that we don't have to read source code.
- edf13 5y agoYou can’t cover every usage possibility in docs… having the code available allows you to check expected behaviour
- rileymat2 5y agoYou also can’t tell what is supported behavior and what is implementation coincidence from the code…
- c0l0 5y agoBecause documentation is what is needs to be: A simplified and necessarily incomplete description of program behavior. It's a trade-off, since a complete and exhaustive description of all intricacies of potential program behavior would be at least as complex as the definition (= its source code) of said program. If you happen to have a question that ends up on the wrong side of that trade-off between documentation's completeness and accessibility, you will have to descend into the depths that lie beneath. I believe the redis documentation actually strikes a rather OK balance in that regard.
- staticassertion 5y agoGood docs generally make guarantees and pitfalls clear.
- scraptor 5y agoOf course having documentation is better but that's not a reason not to read the source code if the documentation isn't enough.
- voidfunc 5y agoBecause good docs are like a good search engine: high hit rate for what you want most of the time. The edge cases and quirky impl detail questions are what src is for.
- megapolitics 5y agoI would argue that outlining expected behaviour in edge cases is one of the most important topics for documentation to cover.
- staticassertion 5y ago> The edge cases and quirky impl detail questions are what src is for. Literally the most important thing you can document.