Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Examples are the best documentation

rakhim.exotext.com

Post reply on HN
Print view View original

111–120 of 179 posts

Re: Examples are the best documentation

#111

Post by AlphaSite »

horsawlarway wrote: post #90
harimau777 wrote: post #70

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…

Personally - what you're asking for is type definitions. And it's a blurry line, since type definitions are a good form of documentation. It's just that type-system tooling has mostly replaced the need to go read through the docs for that. I expect to get it easily and obviously in whatever editor or IDE I've configured. I think the prevalence of example based documentation is because of this trend - don't waste time…

Types don’t explain intent or gotchas. They’re also useful, but you need both.

Re: Examples are the best documentation

#112

Post by tliltocatl »

No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too much unsaid assumptions about the order of methods application.

Re: Examples are the best documentation

#113

Post by yjftsjthsd-h »

voidUpdate wrote: post #89
zahlman wrote: post #83

Earlier quoted context omitted.

> I don't use $ in programming except for string interpolation ... but the entire point of the "$JOB" etc. slang is that it's a string interpolation...

Not how I use it, string interpolation would be $"{job}"

That depends on the language. In unix shell,

  echo $JOB
and

  echo ${JOB}
are identical, though the latter is more flexible (Allowing eg. `echo ${JOB:-unemployment}` or `echo ${JOB}SUCKS`).

Re: Examples are the best documentation

#114

Post by TZubiri »

tliltocatl wrote: post #112

No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too muc…

Why not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.

Re: Examples are the best documentation

#115

Post by constant_flux »

harimau777 wrote: post #70

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

Re: Examples are the best documentation

#116

Post by constant_flux »

TZubiri wrote: post #114
tliltocatl wrote: post #112

No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too muc…

Why not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.

I agree. I don't understand some of the black and white thinking in the comments.

Re: Examples are the best documentation

#117

Post by TZubiri »

As someone that reads official documentation instead of stackoverflow threads, I support this motion.

There's a couple other maladies that make for unreadable docs. Another is documenting only the last layer added by the Open Source collaborator and not documenting anything below, for example if I'm making an HTTP client:

http.get() makes an HTTP get request

http.set_tcp_params(param=value) sets the TCP parameter param to value

When you could do:

http.get() makes an http get request, which should be a read only requaest, that doesn't affect state of the server. Parameters are typically passed in the URL with ?param=value&param2=value2 syntax as defined in RFCxxx

http.set_tcp_params() sets parameters of the tcp layer, as defined in RFCxxx, these can include most importantly the MTU which is the max packet size, which might be useful for fitting webpages... (One way to fail in this regard is to use one of those autodocs things, you just lost the battle.

Re: Examples are the best documentation

#118

Post by tliltocatl »

TZubiri wrote: post #114
tliltocatl wrote: post #112

No. Please for the love of Cthulhu. I need documentation. Not examples. They will help with the common cases, but common cases are easy, it's corner cases I'm after. Not type signatures - type systems are that would be sufficiently expressive would be badly unsound and undecidable. I need to know assumption the code takes. Specially so with statefull/object-oriented code, aka "why I hate the builder pattern". Too muc…

Why not both? That way you can use the docs if you are learning the language AND if you already know the language but are looking for deep details.

Of course both is best. But let's get real, once part one is there that's all you will get from the first-party. "Docs? Yes, here is our examples." Than for examples you can at least ask someone else if the lib is sufficiently popular. For the prose - gotta reverse-engineer it yourself.

Re: Examples are the best documentation

#119

Post by shemtay »

constant_flux wrote: post #115
harimau777 wrote: post #70

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

sometimes professionals need to fix shit and need exacting clarity

Re: Examples are the best documentation

#120

Post by OptionOfT »

harimau777 wrote: post #70

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…

The annoying part about Python is that searching for the python docs is hard.

E.g. "Python rstrip" (without quotes) in DuckDuckGo does not lead me to the Python docs on page 1.

Post reply on HN