Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

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.


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

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!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • 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
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            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?

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

    How do I use this? | Other CB clients
    Other Users?
    Others examining the Monastery: (6)
    As of 2020-10-30 17:50 GMT
    Find Nodes?
      Voting Booth?
      My favourite web site is:

      Results (282 votes). Check out past polls.