5 ms·

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 tr

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.

troupo 1y ago
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...
- Paracompact 1y ago
  > 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?
  - troupo 1y ago
    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-stripe-customers-and-auth0-users#introduction https://developer.auth0.com/resources/labs/actions/sync-stri... or https://github.com/stripe-samples https://github.com/stripe-samples and not a "it's enough to deduce parameters from method signature"
    - Paracompact 1y ago
      > "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..." > <the only step usually shown in examples here> 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-facing function is not misplaced at the architectural level, then good examples often make good technical specs redundant (for users) and provide strictly greater value (for users). I'm aware of real world practices. I'm a real world programmer working with real world functional codebases, where parameters material to computations are always exposed explicitly, or at least their monadic context is. It is no pipe dream to highlight these parameters in full examples. What often is a pipe dream is attempting to formalize and then update English language technical documentation. Ironically, one of the biggest offenders I might point to is the Rocq proof assistant. Their documentation has decent example coverage, but where it doesn't have coverage, and instead only has authoritative-sounding technical specs, it is abysmal. I have gone down rabbit holes to find out the real-world implications of typeclass resolution flags like this one (https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-classes.html#coq:flag.Typeclasses-Unique-Instances https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-cla...), for example, only to find out that its behavior has changed from version to version without any update to its technical spec. This is because the spec, being mere English, was not specific enough to even distinguish between these different behaviors.
      - troupo 1y ago
        Fair enough :) I fully agree with your response
        Paracompact 1y ago
        Cheers mate! Thank you for engaging with my radicalism :)
- o11c 1y ago
  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.
  - troupo 1y ago
    Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stripe-customers-and-auth0-users#introduction https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples https://github.com/stripe-samples
    - o11c 1y ago
      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.
      - troupo 1y ago
        Please tell me how you deduce proper payment and auth flows from a function signature alone.
joemi 1y ago
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.
- Paracompact 1y ago
  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.

troupo 1y ago

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...

Paracompact 1y ago
> 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?
- troupo 1y ago
  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-stripe-customers-and-auth0-users#introduction https://developer.auth0.com/resources/labs/actions/sync-stri... or https://github.com/stripe-samples https://github.com/stripe-samples and not a "it's enough to deduce parameters from method signature"
  - Paracompact 1y ago
    > "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..." > <the only step usually shown in examples here> 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-facing function is not misplaced at the architectural level, then good examples often make good technical specs redundant (for users) and provide strictly greater value (for users). I'm aware of real world practices. I'm a real world programmer working with real world functional codebases, where parameters material to computations are always exposed explicitly, or at least their monadic context is. It is no pipe dream to highlight these parameters in full examples. What often is a pipe dream is attempting to formalize and then update English language technical documentation. Ironically, one of the biggest offenders I might point to is the Rocq proof assistant. Their documentation has decent example coverage, but where it doesn't have coverage, and instead only has authoritative-sounding technical specs, it is abysmal. I have gone down rabbit holes to find out the real-world implications of typeclass resolution flags like this one (https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-classes.html#coq:flag.Typeclasses-Unique-Instances https://rocq-prover.org/doc/V8.19.0/refman/addendum/type-cla...), for example, only to find out that its behavior has changed from version to version without any update to its technical spec. This is because the spec, being mere English, was not specific enough to even distinguish between these different behaviors.
    - troupo 1y ago
      Fair enough :) I fully agree with your response
      - Paracompact 1y ago
        Cheers mate! Thank you for engaging with my radicalism :)
o11c 1y ago
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.
- troupo 1y ago
  Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stripe-customers-and-auth0-users#introduction https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples https://github.com/stripe-samples
  - o11c 1y ago
    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.
    - troupo 1y ago
      Please tell me how you deduce proper payment and auth flows from a function signature alone.

joemi 1y ago

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.

Paracompact 1y ago
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.