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

“This is the worst documentation I have ever seen in my life”

github.com

Post reply on HN
Print view View original

31–40 of 112 posts

Re: “This is the worst documentation I have ever seen in my life”

#31

Post by SeeDave »

llimllib wrote: post #3

~13 years ago (!) I worked with the Amazon Seller API and left this comment in my own source code: // the XML returned from this request is *mind-bogglingly* bad. Terrifyingly bad. // a completed batch looks like this: // batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 // and an incomplete batch like: // batchid=363778361 status=In Progress /…

batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17

Philosophically speaking, is this any different than 'syntactic salt' for a 'Batch' JSON object? ;)

Re: “This is the worst documentation I have ever seen in my life”

#32

Post by TT3351 »

m45t3r wrote: post #18
forsaken wrote: post #13

Earlier quoted context omitted.

Sphinx supports this for Python: https://www.sphinx-doc.org/en/master/usage/extensions/doctes...

This is actually something from Python's stdlib: https://docs.python.org/3/library/doctest.html Really underrated.

I seem to recall a talk given at one point that demonstrated a scheme that would reverse engineer functions out of whole cloth based only on docstrings and doctests, but of course I can't find it now.

Re: “This is the worst documentation I have ever seen in my life”

#34

Post by abernard1 »

llimllib wrote: post #3

~13 years ago (!) I worked with the Amazon Seller API and left this comment in my own source code: // the XML returned from this request is *mind-bogglingly* bad. Terrifyingly bad. // a completed batch looks like this: // batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 // and an incomplete batch like: // batchid=363778361 status=In Progress /…

I kid you not, I know exactly what you're talking about there. I also wrote my own regex parsers with fast-forward and rewind tokenizers, because it was so dreadful. I wouldn't normally do that.

There's also 4 (4!!!) different ways of returning errors in the MWS Feed APIs when used from Java. Given the number of entities, and the fact that they're combinatorial I had to do some of the craziest Scala code I've ever written because duplication was just too bad to handle for how critical that code was. To do it in a bulletproof way, that error handling for MWS feeds inherently has 2^4 control flows * N entities = 16N code paths at like 100-200 lines a piece if you didn't use some higher order abstractions.

Re: “This is the worst documentation I have ever seen in my life”

#39

Post by itronitron »

llimllib wrote: post #3

~13 years ago (!) I worked with the Amazon Seller API and left this comment in my own source code: // the XML returned from this request is *mind-bogglingly* bad. Terrifyingly bad. // a completed batch looks like this: // batchid=363777811 status=Done dateandtime=09/18/2007 09:53:10 PDT activateditems=335 numberofwarnings=0 itemsnotacivated=17 // and an incomplete batch like: // batchid=363778361 status=In Progress /…

Were they not using a standard XML serialization library?

Re: “This is the worst documentation I have ever seen in my life”

#40

Post by mijoharas »

m45t3r wrote: post #16
mijoharas wrote: post #8

Earlier quoted context omitted.

obligatory "Rust docs can do this"[0] (quite a nice feature tbh). [0] https://doc.rust-lang.org/rustdoc/documentation-tests.html

Python can too, and I think most other languages are inspired by it. https://docs.python.org/3/library/doctest.html

oh cool, didn't know that was where it came from, thanks for the pointer!
Post reply on HN