Beefy Boxes and Bandwidth Generously Provided by pair Networks
more useful options
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??

++ for an amazingly comprehensive reference list.

However, in trying to absorb the 39 various bullet points of proposed guidelines on API design, I'm reminded of the Justice Stewart quote on pornography:

"I shall not today attempt further to define the kinds of material I understand to be embraced . . . but I know it when I see it . . . "

Of the various guidelines, I like Bloch's best because of the short and clear concepts they present. The others need to be parsed and understood and use several metaphors that impede clarity unless you already know what the authors are talking about.

Part of the challenge in giving API guidelines is that API style is context dependent as well. Different language styles lead to different API styles and what works best for one language might not work best for another.

For the reference section, I'd suggest adding things like Tufte's VDQI, as the principles he lays out for eliminating non-data ink have some nice parallels to API design -- particularly of the Conway style. On the other hand, sometimes, as with named parameters, clarity and extendibility means more ink (er, pixels), not less.

Separately, one reason that I like test-driven development is that by writing unit tests first before writing code, I wind up "using" my API before I implement it. At that point, the cost of change for the API is minimal. Even as code is implemented and additional features are added, the cost of change at that point is still pretty low. I'll frequently do several drafts of the API just while writing the test file.

-xdg

Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.


In reply to Re: On Interfaces and APIs by xdg
in thread On Interfaces and APIs by eyepopslikeamosquito

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 wandering the Monastery: (4)
    As of 2014-09-24 02:48 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      How do you remember the number of days in each month?











      Results (244 votes), past polls