151–160 of 179 posts
Radical opinion: If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, the method is probably trying to do too many things. In particular, I don't want to have to learn half a dozen footguns because of a leaky abstraction.
Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…
Did you stop to consider that perhaps other people learn differently than you, and find examples as a way to soften the friction that context switching causes in a job? I don't understand the resistance to examples being a part of documentation (and not a bonus).
I think harimau777 was just expressing his opinion, like the blog owner.
Earlier quoted context omitted.
This is the right answer. Everyone who disagrees with you are amateurs. A Javadoc-esque API doc is the minimum requirement for a serious language/library. Examples and tutorials are nice too, but the API doc can be automatically generated in every serious language so not having it is just plain unacceptable. Tutorials, articles and examples etc are fine too, they can be combined with the API doc like Java does. But t…
I think it's a bit harsh to call everyone who disagrees amateur. However, anecdotally it doesn't feel very incorrect. When I do pair programming with less-experienced developers, I'll often watch them glance at the API docs, skim over the technical details, look at the example, copy paste it, and then be confused why it doesn't work. Then I pointedly suggest reading the specific paragraph that explains the confusion…
If you don't even know the language well enough to read docs I'd say you're an amateur. And if you're one of those people who just chronically don't read docs you're definitely an amateur. I mean you may have a job and you may even build stuff that kind of works, but unless you're sitting down and looking closely at the details you're not doing things right. You can't be. Doing things right requires looking closely at the details.
And I know from experience that there's a vast number of employed amateurs who write nothing but legacy code.
I try to write good documentation for my programs, although it helps if other people (who do not already know the working of the program) will review it in order to suggest improvements.
Earlier quoted context omitted.
Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples
I see nothing there that seems fundamentally problematic, but I'm not writing type definitions for someone's entire commercial API. Callbacks are always Hell of course.
Earlier quoted context omitted.
Real world isn't about calculating a fibonacci sequence. Real world is usually a combination of - read data - trasform data - obtain auth - prepare data in proper formats - - get results back. Perhaps an error? A stream? A specific format? Could we do retries? That's why a full example would look like this: https://developer.auth0.com/resources/labs/actions/sync-stri... or https://github.com/stripe-samples and not a…
> "it's enough to deduce parameters from method signature" You don't quote me well. Here's what I actually wrote: "If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, then..." > Then those are poor examples. I'm not defending that poor examples beat out good technical specs, or even that bad examples beat out bad technical specs. Merely that, if a user…
Radical opinion: If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, the method is probably trying to do too many things. In particular, I don't want to have to learn half a dozen footguns because of a leaky abstraction.
Why rely on someone to intuit what you could just simply state explicitly? That sounds like you're just asking for trouble if someone doesn't think/intuit in exactly the same way that you do.
It's merely that I think unstructured English is not a good language for communicating knowledge of how to use an API.
Earlier quoted context omitted.
> "it's enough to deduce parameters from method signature" You don't quote me well. Here's what I actually wrote: "If the technical spec of a method cannot be intuited from the signature and a handful of canonical examples of usage, then..." > Then those are poor examples. I'm not defending that poor examples beat out good technical specs, or even that bad examples beat out bad technical specs. Merely that, if a user…
Fair enough :) I fully agree with your response
Please don't follow this advice! The best thing about old school Python was that I could reliably pull up the documentation for a library and it would clearly list the arguments and return values for each function. Now when I look at the documentation for many JavaScript, and even Python, libraries it's just examples. That's great if I'm trying to just throw something together as quickly as possible, but not if I nee…
I think this is almost provably true, for the simple reason that detailed technical documentation can be a substitute for examples, but the reverse isn't true. 1. If you want an example and the docs have an example, great. 2. If you want technical details and the docs have technical details, great. 3. If you want an example but the docs only have technical details, you can still get what you want by spending longer t…
I'm not sure it's inefficient. It gives you the knowledge what is and isn't possible and also the semantics of what you actually do, all things you need to have later anyway. Relying only on examples is a great way to miss unintended side-effects or other consequences.