Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
IO:All is controversial to me, as I have alluded to here.

I like API's to be simple, straight forward, and they need to involve as little 'theory of operations' as possible. In my question above, it turns out IO:All blocks the user from doing something nonsensical, yet, the API intrinsically implies such a thing is possible. (Not to be picking on IO::All, I'm just using it as an example). Another API discourse -- Many API's, for example Linux PAM have a rather bad 'theory of operations', meaning you have to call a lot of functions in a certain order to get things right. I like functions to be one-shot-one-kill and do what they say, in the right context. Required domain knowledge should be internal to the API methods, not be forced upon the caller. Java methods are typically the anthithesis of this, requiring tons of methods across various classes to get any functional unit of work done. Brevity and simplicity in the interface is lacking. IO::All does a good job here (most API's don't), and it even does checking to block the crazy implications of routing a directory to a socket, there is another issue.... normality and obviousness.

If you didn't have the documentation, and only the method names, you should know exactly how it works and it should work as expected. You also shouldn't be able to blow your leg off, much less shoot yourself in the foot.

As for breaking API's, I've seen this done to me millions of times and it annoys me to no end. Not in Perl, but C++. I guess a good way to start in Perl it to have most functions take named parameters (hashes) and not to change method signatures. But that takes discipline and up-front design -- not everyone is into that. With C, have your functions take structures and add to the end of them to preserve binary compatibility -- but even this can be hard. It's design-up-front. Not always easy to see the future.

But in all, it's an artform, and stringency that removes fun and coolness isn't always worth it. IO::All has some cool ideas, but it walks a fine line between cool and too cool. But is there such a thing as too cool? Only for production work.


In reply to Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by flyingmoose
in thread Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by kal

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • Outside of code tags, you may need to use entities for some characters:
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others having an uproarious good time at the Monastery: (8)
    As of 2014-07-11 23:31 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      When choosing user names for websites, I prefer to use:








      Results (236 votes), past polls