Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?"

IO:All is controversial to me, as I have alluded to here.

I like API's to be simple, straight forward, and they need to involve as little 'theory of operations' as possible. In my question above, it turns out IO:All blocks the user from doing something nonsensical, yet, the API intrinsically implies such a thing is possible. (Not to be picking on IO::All, I'm just using it as an example). Another API discourse -- Many API's, for example Linux PAM have a rather bad 'theory of operations', meaning you have to call a lot of functions in a certain order to get things right. I like functions to be one-shot-one-kill and do what they say, in the right context. Required domain knowledge should be internal to the API methods, not be forced upon the caller. Java methods are typically the anthithesis of this, requiring tons of methods across various classes to get any functional unit of work done. Brevity and simplicity in the interface is lacking. IO::All does a good job here (most API's don't), and it even does checking to block the crazy implications of routing a directory to a socket, there is another issue.... normality and obviousness.

If you didn't have the documentation, and only the method names, you should know exactly how it works and it should work as expected. You also shouldn't be able to blow your leg off, much less shoot yourself in the foot.

As for breaking API's, I've seen this done to me millions of times and it annoys me to no end. Not in Perl, but C++. I guess a good way to start in Perl it to have most functions take named parameters (hashes) and not to change method signatures. But that takes discipline and up-front design -- not everyone is into that. With C, have your functions take structures and add to the end of them to preserve binary compatibility -- but even this can be hard. It's design-up-front. Not always easy to see the future.

But in all, it's an artform, and stringency that removes fun and coolness isn't always worth it. IO::All has some cool ideas, but it walks a fine line between cool and too cool. But is there such a thing as too cool? Only for production work.

Comment on Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?"

Replies are listed 'Best First'.
Re: Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by kal (Hermit) on Mar 23, 2004 at 15:18 UTC
I'm not sure whether I agree with your "theory of operations" statement; although of course that would depend on whether we draw the "as possible" line in the same place. For me, a module should give you a good idea of how it is operating. With IO, for example, being able to tell the difference between buffered and unbuffered IO is sometimes crucial. I'm not sure you can ever get away from that kind of thing completely, or if you would ever want to (i.e., what is the opportunity cost?) The thing about method names sounds like an orthogonality argument, which is probably quite right. You could probably make it orthogonal, but for me Perlishness doesn't require orthogonality (although it's always good). And, the documentation does tell you about < and > and when and how they work (maybe it has been changed since you looked). I suspect I wouldn't use the overloaded operators. But, you never know. I like the shellness of them. Perhaps some of this is a case of "too cool" though. Hmm, I'm not sure.	[reply]
Re: Re: Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by flyingmoose (Priest) on Mar 23, 2004 at 15:59 UTC
FYI -- my comments about 'theory of operations' and the need to have a heavy and strict order of method calls (see PAM code in C, the Windows API, Java socket API's, whatever) is annoying and could be cleaned up -- but that's not a comment about IO::All, but rather API design in general. You lost me when you speak of 'an orthogonality argument', what are you proposing should be othogonal to what? Again, the commentary of IO::All is just interlaced into my post as reference, I think the '>' operators are indeed (1) succinct but are not (2) obvious enough. My biggest issue with API design is that API's are not clean and succint enough, and IO::All does a good job in this case. But it's sketchy when it comes to expected behavior, IMHO -- there are obviously tradeoffs to consider between the two.	[reply]
Re: Re: Re: Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by kal (Hermit) on Mar 23, 2004 at 16:13 UTC
The "othogonality" I was referring to (I should stop using that word; it's ugly) was about being able to use the overridden operators in all circumstances. You expected something to work, and it didn't, because of the circumstance. I have to say, I like both the '>' and '>>' operators - they work just like in the shell, pretty much. '>>' is also a bit C++-ish. But, maybe it's just my brane.	[reply]
Re: Re: Re: Re: Re: Ingy's "Swiss Army Light Sabre" - or, "how do you design your APIs?" by stvn (Monsignor) on Mar 24, 2004 at 15:11 UTC


Do you know where your variables are?
	PerlMonks