←back to thread

Examples are the best documentation

(rakhim.exotext.com)
409 points Bogdanp | 2 comments | 09 Oct 25 19:34 UTC | HN request time: 0.404s | 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 #
1. joemi ◴[10 Oct 25 22:07 UTC] No.45544372[source]▶
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.
replies(1): >>45547246 #
2. Paracompact ◴[11 Oct 25 07:07 UTC] No.45547246[source]▶
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.