[sf-perl] REST data parsing

[Joe McMahon]

On Wed, Sep 8, 2010 at 1:37 PM, Joe Brenner <doom at kzsu.stanford.edu> wrote:
> Reviews on CPAN indicate that JSON went through an API from 1.0 to 2.0,
> though this sounds like it went through three changes:
>
>> It went from objToJson to to_json and encode_json, with different
>> options.
>
> There's been all too much of this going around lately.  I get the
> feeling that the present generation of open source programmers flat-out
> doesn't understand the issue.  They just expect everyone else to just
> deal with whatever changes they feel like making.

I ranted politely about this on Perlmonks a while back; did anyone
*else* get caught by the point release change in WWW::Mechanize that
turned on autocheck by default? At Yahoo!, it was six months before we
managed to find all of the little utility scripts lying around that
used WWW::Mechanize without subclassing it, so they all died hard the
first time they had a page-fetch problem, instead of diagnosing it and
moving on the way they used to, and there's no guarantee there isn't
another seldom-used one still ticking away somewhere in someone's
/bin.

Summarizing from there:
 - If you have to deprecate, transition: provide the old interface for
a release or two before removing the old.
 - Warn that the new behavior will be happening if the user hasn't
specifically coded to the new interface.
 - Never change an interface in a way that hides the change.
 - If you need to keep the same API but change function, provide an
environment variable that allows a global override to the old
behavior.
 - Document: write POD that emphasizes at the top that the API will
change, and when it will change.
 - Have your error messages actually tell the user what was wrong:
"request failed. did you forget to turn off autocheck?"
 - Polite (and good) programmers don't pull this crap.

I got a surprising number of "well, if someone just installed a module
and didn't read the documentation, then they should expect to have
problems."  Allow me to say: NO THEY SHOULDN'T. If you are going to do
something that *might* screw up someone else's software, it is your
duty as a programmer to do everything you reasonably can to prevent
that, even if it's simply "sorry, we've changed this, you'll need to
fix the call at line X to include the gorbleplatz parameter".

Note: WWW::Mechanize id great, and I really respect the programmers
who built it; I just think this one time they dropped the ball.

Hm, could have done a talk from that. :)