I strongly prefer functions with simple and consistent interfaces. Heavily overloaded interfaces get complex, and maintaining the API is too much work for my taste. Furthermore if the person is using none of your APIs correctly, it becomes much harder to give advice about what they are doing wrong.

I would KISS, clearly document what the API is, and provide careful error checks. Furthermore if you are developing a larger body of code I would suggest settling on a generic interface pattern that suits you and trying to use that consistently. There are many possible interfaces that could work, but based on experience I have to say that named interfaces are far less error-prone and lead to much more readable code than positional logic.

If you want to have more possible input formats, add more functions and clearly name them. Make those functions all wrappers around the one you find easiest to work with. This offers flexibility, but does not unduly complicate your module. The wrappers need but be written once and then left. You have done the critical thing - created a single point of maintainance for any future improvements to the module. From the user's point of view the complexity of the interface lies in the number of methods they make use of.

UPDATE
I forgot to point out the exception that I have for the rule about not overloading interfaces. If your interface has a hook for a thing with overloadable defined behaviour, that is just fine by me. Internally to your module you are consistent in your use of the parameters. However the user can do what they want.

The two classic examples of things with overloadable defined behaviour are objects and anonymous functions. An anonymous function has one piece of overloadable behaviour, it can be called. That will do something, anything. There is an expectation about what it should do in the function, but the hook is available. Similarly an object has multiple overloadable behaviours called methods. Provide the right methods the code works. But each defined method is a defined hook that can usefully be used to customize what will happen.

If this comment about objects (and anonymous functions) does not make sense to you, then you have not grasped the essence of OO...

In reply to Re (tilly) 1: Complexity of API argument passing by tilly
in thread Complexity of API argument passing by Masem

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!
  • 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, details, 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, summary, 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.