Comment by scrollaway
5 years ago
It's not. Good quality codebases do exist, and generally are fairly well self-documented.
Typings, well-named functions and variables, consistent APIs and once in a while, a comment to summarize rationales and point out edge cases, and a README file to explain the setup and entry points.
That is generally all you need in terms of documentation. I've dealt with plenty of codebases like these and they're a delight to learn.
> they're a delight to learn
Boto3, its massive. The only reason its tolerable is that its got a large amount of accurate documentation. On the face of it, its an utter arse, because the "client" section of the library is deeply unpythonic (not in the oh its not pretty sense, as it its barely OO and uses capitals for argument names)
If that was "self documenting" I wouldn't be using it.
Take flask for example, its usable because its got good documentation and its well thought out.
but, as I keep on having to tell people. Good function names and tying is not documentation. These tell you what but not why. You don't need documentation if you are working on the same codebase day in day out. But if you have to pick it up again after 6months, you'll wish that you had properly documented it.
I get that you are proud that you don't need documentation. I don't need documentation, I want it because it makes my life 500% easier.
What are you talking about? Boto3 is extremely well documented, and is absolutely not self-documenting. It's a mostly autogenerated API, and a horrible example to use for this.
I don't think you understand what my post is trying to convey. Documentation isn't a sin, it's great when necessary. In the case of boto, it's obviously necessary. In the case of Flask (a framework where you're not going to read the code), it's obviously necessary.
You'll notice, if you read through the Flask codebase, that it's only documented in terms of user-facing functions, which end up in the official end-user documentation. In that sense, the codebase itself is in fact mostly self-documenting.
There's a difference between end-user documentation and developer-facing documentation.