in reply to Complexity of API argument passing

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...

  • Comment on Re (tilly) 1: Complexity of API argument passing

Replies are listed 'Best First'.
Re: Re (tilly) 1: Complexity of API argument passing
by Masem (Monsignor) on Jul 14, 2001 at 02:35 UTC
    Would it be unreasonable to offer both approaches, the individual functions as well as the 'do-all' approach?

    Specifically, in my case, I will be adding data to the internatl structure by a function "add_data_point", which is explicit in what it takes such that it could be prototyped. ($$;$% for example). I could then define various functions "add_data_from_TYPE", TYPE being replaced by what method of data storage I would expect there (hash of hashes, array of hashes, etc). Each function would call add_data_point repeated to add the data to the internal storage in the appropriate manner. This would provide the consistent interface for the API. Again, these functions could be prototyped without problems. I could then provide one last function "add_data", which would do the checks that I suggest in the root node of this thread, and then call out to the specific "add_data_from_TYPE" calls depending on the type of structure. This provides more of the "intelligent" interface for the API, without adding a lot of extra code.

    Dr. Michael K. Neylon - mneylon-pm@masemware.com || "You've left the lens cap of your mind on again, Pinky" - The Brain
[reply]
      I would wonder why.

      It sounds like a lot of work, and a lot of complexity. It makes extending your interface later much harder. It makes it harder to offer a good error check. This "accepts anything" function is going to be much harder to explain. And it introduces a significant point of confusion for people trying to understand how to use your module.

      I simply don't see that what you are adding is valuable. It wouldn't be for me. I really prefer to have several simple ideas that fit together really well than a monolithic idea that tries to solve all of my problems.

[reply]

In Section Meditations