Why do DOM interfaces suck so much?

Something occurred to me today that I (as well as probably you) have known all along; DOM interfaces suck. As I was cruising the Gecko DOM Reference Guide looking for some obscure method to jog my memory on how it works, I started wandering off onto other random methods like evt.initMouseEvent() and window.find(), both of which have horribly stupid dumb idiotic interfaces. Tell me, what is great about an API that forces you to pass in five optional arguments just to get to the one you want? For example, here is the interface for window.find:

API for window.find

window.find(aString, aCaseSensitive, aBackwards, aWrapAround,

    aWholeWord, aSearchInFrames, aShowDialog);

And likewise, check out this one that allows you to simulate events in the browser:

initMouseEvent interface

vent.initMouseEvent(type, canBubble, cancelable, view, 

    detail, screenX, screenY, clientX, clientY, 

    ctrlKey, altKey, shiftKey, metaKey, 

    button, relatedTarget);

As far as I'm concerned, since the DOM is a slave to JavaScript, it should obey its rules and live in its spirit. A good interface should follow this simple rule. "All required arguments should have their own parameter; all optional arguments should live in one single parameter, placed as the last parameter, as an object."

What does that mean?

If method foo takes five arguments, but the last three are optional, the interface should take in three arguments like this:

pretend foo interface

foo(requiredField1, requiredField2);

// or...

foo(requiredField1, requiredField2, {

  opt_field1: bar,

  opt_field2: baz,

  opt_field3: thunk

});

// or...

foo(requiredField1, requiredField2, {

  opt_field3: thunk

});

Optional fields should all have defaults. Which brings up another thing... some existing interfaces could also use a little face-lift enhancements. For example, addEventListener to one extent follows the rules mentioned above. But when do you 'ever' set the third flag to 'true', eg:

element.addEventListener

document.getElementById('el').addEventListener(

  'click',

  doFoo,

  false

);

I think the Mozilla team should do some testing on how often a developer actually sets that third parameter to true. I'm willing to bet it's less than 0.001%. There's no reason it should not be optional with a default set to false.

Last but not least...

We should all remember this from way back... I just gotta say, wtf was this all about?

wonky.window.open

winRef = window.open(strUrl, strWindowName [, strWindowFeatures]);

// for example...

winRef = window.open(

  'foo.html', 

  'uh, a name?', 

  'menubar=yes,location=yes,resizable=HELL_NO,scrollbars=yes,status=maybe,wtf=omg'

);

To me this looks like a poor mans utility function who didn't want to waste his time using a JavaScript library. Oh no no no, you get this built right into the browser! Yeah, for free! Granted, these interfaces were written in the 90's, so I can't say much, I was still fiddling with <blink>. Cheers.

follow me

i am dustin diaz