←back to thread

Examples are the best documentation

(rakhim.exotext.com)
409 points Bogdanp | 4 comments | 09 Oct 25 19:34 UTC | HN request time: 0.963s | source
Show context
Paracompact ◴[10 Oct 25 06:47 UTC] No.45535991[source]▶
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.

replies(2): >>45536189 #>>45544372 #
troupo ◴[10 Oct 25 07:23 UTC] No.45536189[source]▶
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...

replies(2): >>45536987 #>>45541711 #
1. o11c ◴[10 Oct 25 17:45 UTC] No.45541711[source]▶
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.

replies(1): >>45542770 #
2. troupo ◴[10 Oct 25 19:27 UTC] No.45542770[source]▶
Please constrain function signatures of these: https://developer.auth0.com/resources/labs/actions/sync-stri... and https://github.com/stripe-samples
replies(1): >>45543553 #
3. o11c ◴[10 Oct 25 20:42 UTC] No.45543553[source]▶
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.

replies(1): >>45547009 #
4. troupo ◴[11 Oct 25 06:10 UTC] No.45547009{3}[source]▶
Please tell me how you deduce proper payment and auth flows from a function signature alone.