Comment by Paracompact
5 days ago
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.
No. Examples are there to show how to use this method, and other methods in conjunction.
You can intuit all you want from a method signature, and then you will fail to produce working code because you missed a config, or a preparation step, or don't understand how to process the results, or...
If the type signature isn't enough to fully constrain that, you need to fix your typing.
If you have a `Foo` object, it should always be able to do every possible thing a `Foo` can do.
If you need to do something first, it should be a required argument to whatever lets you construct a `Foo` in the first place.
Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples
2 replies →
> because you missed a config, or a preparation step
If the specific values of parameters of your mutable state are material to the outcome, then the example is incomplete if they are not specified. Similarly, you wouldn't use `fib(x) = 3` as an example without specifying `x = 4` in your context.
> don't understand how to process the results
Not sure when this would be the case. Do you have an example in mind?
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
- <the only step usually shown in examples here>
- 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"
3 replies →
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.
Including the technical spec explicitly is still a good idea. Examples without a word of summary would just be strange!
It's merely that I think unstructured English is not a good language for communicating knowledge of how to use an API.