Re:Examples Are the Best Documentation
by tliltocatl on Friday October 10, 2025 @12:13PM
(#45540594)
No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too much unsaid assumptions about the order of methods application.
[ Parent
| on HN ]
Why not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.
Re:Examples Are the Best Documentation
by constant_flux on Friday October 10, 2025 @12:23PM
(#45540686)
I agree. I don't understand some of the black and white thinking in the comments.
Re:Examples Are the Best Documentation
by tliltocatl on Friday October 10, 2025 @12:25PM
(#45540701)
Of course both is best. But let's get real, once part one is there that's all you will get from the first-party. "Docs? Yes, here is our examples." Than for examples you can at least ask someone else if the lib is sufficiently popular. For the prose - gotta reverse-engineer it yourself.