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

Comment on

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

There are already some really excellent comments here. I agree very much with flyingmoose that an ideal would be that if you only knew the method names, you would still understand the API/class. Personally, I think this is something every API designer should strive for, but few ever actually reach. I also agree with dragonchild that an obsessive drive for simplicity and domain experience are two characteristic likely to be found in all good API desingers. (Although on occasion, a fresh perspective is good, not that this is mutually exclusive with domain experience, but sometimes good abstraction requires a distancing of ones self from the details of the domain.)

To these points I would like to add consistency. To me, this is an equally important element of a good API and one I strive to instill in every one I design. Consistent handling in method/function/variable naming conventions as well as in argument names and argument ordering (something I think is key to perl since it lacks named parameters). An obsessive drive to organize (a place for everything and everything in its place) is also something I think most good API/library designers have, a disorganized API can kill other positive aspects very quickly.

If you are instested in further study of API design, I would like to recommend this book. Reusable Software - The Base Object-Oriented Compontent Libraries by Bertrand Meyer, it is heavy on Eiffel (whose base libraries it is talking about), but really really insightful and smart. I believe that Eiffel actually begun not as a language, but as an attempt to "understand the fundemental structures and paradigms of software development". This book is basically about that process. It is one of the only books I have found that actually discusses the principles of good library construction in detail, including class names, proper use of inheritance, ideal class size, etc. etc. I actually keep it on my "within-arms-reach" shelf, next to the O'Reilly Perl catalog and my favorite Addison Wesley titles (Refactoring, Design Patterns, Pragmatic Programmers, etc).

-stvn

In reply to Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by stvn
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
  • 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?
    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 scrutinizing the Monastery: (13)
    As of 2015-07-06 22:04 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      The top three priorities of my open tasks are (in descending order of likelihood to be worked on) ...









      Results (83 votes), past polls