3 ms·

Python is my preferred language to work in, and has been for many years. It's not the only language I've used, though, and I've had basically the inverse of yo

Python is my preferred language to work in, and has been for many years. It's not the only language I've used, though, and I've had basically the inverse of your problem from time to time: people who think running an API-documentation generator over their statically-typed code, so that it just spits out a big list of functions with their return types, parameter names and parameter types, is "documentation". Now, it may be you come from a world where that's the standard way to do things and you've gotten used to it and mostly don't notice just how much further research and digging it takes to figure out from "Frobnitzable bunglify(Widget[] w, int c)" what it is exactly that it, um, does. But it's hard to knock people for not writing documentation when advocating for a language feature that encourages people not to write documentation! My experience is that it's easy to fail to produce useful documentation in just about any programming language, and that languages' choice of type systems does not correlate significantly with the quality of documentation of key libraries and tools.

ioddly 8y ago
I think there's a fair bit to be said for API discoverability. I was working with the TypeScript compiler API earlier this year, which is an excellent piece of software but not particularly well documented, and I was able to discover a fair bit of what I needed through Intellisense and well-named functions. Python is also fairly good in this regard, though not quite as convenient, with the help() function (it's been a long time since I saw one of these but I do recall a handful of libraries breaking help with "clever" metaprogramming). Ceteris paribus, I'd rather have the nice completions.
- ubernostrum 8y ago
  My point is mostly that real, good, documentation is a lot of effort no matter the language or its type system, and that once you've worked in a language long enough you internalize whatever processes you use to compensate for common shortcomings in that language's documentation. Which then means it's often not a fair comparison to be thrown into a new language, requiring new processes to compensate, that you aren't used to and so notice more. I used to point out the same thing way back in the day when people argued that tables were "easier" for web page layout than CSS, because of all the hacks involved in doing CSS layout 15-ish years ago. It wasn't actually that tables didn't require hacks, it was that people had been doing tables long enough they'd forgotten how much of it consisted of hacks, and so the new and unfamiliar stuff they had to learn to make CSS work only seemed more complicated.
- int_19h 8y ago
  Well-designed APIs can be self-documenting to a significant extent with the right choice of names (and things they name, as well). But it takes as much if not more effort to do this right, as it does to write quality docs.

ioddly 8y ago

I think there's a fair bit to be said for API discoverability. I was working with the TypeScript compiler API earlier this year, which is an excellent piece of software but not particularly well documented, and I was able to discover a fair bit of what I needed through Intellisense and well-named functions. Python is also fairly good in this regard, though not quite as convenient, with the help() function (it's been a long time since I saw one of these but I do recall a handful of libraries breaking help with "clever" metaprogramming). Ceteris paribus, I'd rather have the nice completions.

ubernostrum 8y ago
My point is mostly that real, good, documentation is a lot of effort no matter the language or its type system, and that once you've worked in a language long enough you internalize whatever processes you use to compensate for common shortcomings in that language's documentation. Which then means it's often not a fair comparison to be thrown into a new language, requiring new processes to compensate, that you aren't used to and so notice more. I used to point out the same thing way back in the day when people argued that tables were "easier" for web page layout than CSS, because of all the hacks involved in doing CSS layout 15-ish years ago. It wasn't actually that tables didn't require hacks, it was that people had been doing tables long enough they'd forgotten how much of it consisted of hacks, and so the new and unfamiliar stuff they had to learn to make CSS work only seemed more complicated.
int_19h 8y ago
Well-designed APIs can be self-documenting to a significant extent with the right choice of names (and things they name, as well). But it takes as much if not more effort to do this right, as it does to write quality docs.