Re: jQuery Overloading Strategy -- What Not To Do

On Sep 15, 1:23 pm, Scott Sauyet <scott.sau...@xxxxxxxxx> wrote:
dhtml  wrote:
Scott Sauyet wrote:
dhtml wrote:
Scott Sauyet wrote:
Do you think all overloading in JS is a problem?  

The implementation of overloaded methods is of course problematic, and
the only justification I can see for it is in *perceived* API
[ ... ill-considered 'getVal'/'setVal' example removed ... ]

Name 'getVal' is a contrived plastic example. Methods that are well-
named, simple, self-documenting. Obviates the need for documentation.

Sorry, I wasn't thinking about it that way.  I was thinking about
jQuery's "val" function which is both an accessor and mutator for it's
objects wrapping INPUT and SELECT elements.

A cleaner example would be, say, `height`.

It's certainly a debatable point as to whether the `setHeight`/
`getHeight` pair is more complicated than a single `height` function,
but if nothing else, the latter has fewer symbols to remember.
Perhaps it's slightly easier to learn with the `set/get` versions, but
it's no easier to use, and the complexity of implementation is not
significantly different.

So my question was really whether you objected to that sort of
overloading.  Or perhaps even if you object as strenuously to that
sort of overloading as you do to, say, the overloading of the main
jQuery function.

In fact, it'ss arguably more complicated.  It's certainly harder to
document well.  But there is still some persistent feeling that the
API with the single function is cleaner.

Whose feeling? Can we stick to pros/cons?

Mine.  Why should I care about yours?  :-)

I really am talking about pros and cons.  In one very naive way, it's
almost tautological that an API with a single function is simpler than
one with two functions.  So there is at least one pro to an API that
can be used this way:

    var r = new Rectangle(20, 10);
    alert(r.area()); // 200
    alert(r.area()); // 300
    alert(r.height()) // 15

over one that works like this:

    var r = new Rectangle(20, 10);
    alert(r.calculateArea()); // 200
    alert(r.calculateArea()); // 300
    alert(r.getHeight()) // 15

Do you object to the single-function API?

My question is whether this vague and fuzzy feeling that the single-
functioned API is simpler could ever be enough of a reason for
complicating the implementation.  I'm entirely mixed on this.  I'm all
for complicating implementation to simplify an API.  But

But an API to do what?

Whatever.  If I want to use an API to handle a certain facet of my
system, I would rather have a simple API.  If I want to read a file
into a String using Ruby, it's as simple as

    text =

In Java, I'd need to use about ten lines of code, invoking
FileInputStreams, BufferedReaders, IOExceptions, StringBuilders, and
so on.  Ruby clearly has a simpler API for this.

If I'm using an external API (even one I've written myself) in my
code, I want the code using it to be as clear as possible, and that at
the expense of how easy the API is to write.

Methods that do more than one thing are more complicated.

Yes, but so are objects that do more than one thing.  The question is
whether that complication is ever justified.

Objects have more than one behavior. An object is a set of (hopefully
well-named) properties and/or methods. Methods shouldn't.

That's just restating your objection.  Do you think overloading is
never justified?

Take a panel, for example, might have "show" ahdn "hide". Now you
could potentially make a method that does both:

e.g. setDisplay(bShow);

But what for? That just means that the API needs documentation,
whereas someting like "show" -- do you get what that should do?

Can `show` be animated?  Do you need a parameter that describes what
animation to use?  How about the duration?  And if it's animated,
could I also supply a callback to run when it's done?  If we have an
API that uses `show` to handle a plain change to visibility, a simply
animated one, or one that's animated with a followup callback, is this
somehow more complicated than an API like this?:

    animatedShow("fadeIn", 600)
    animatedShowWithCallback("slideUp", 400, function()

Can we use CSS transitions instead? I can do it in JS but transitions
would be a lot simpler.

Yes, the implementation of a single "show" function to handle these
possibilities is more difficult than any individual one of the above
would be, but the total code is not likely to be much harder.  This
extended API is clearly more difficult to remember.  I would argue
that it's more difficult to use as well.

The extended API is harder to remember, there, but i'd rather not
extend it like that. The `onshow` callback can be generic and then up
to the client of the API to shadow/replace it.


I have another case that I'm using a lot in my current project.

    var handleXYZ = function(param) {
      each(makeArray(param), function(item) {

I receive (from an external source) references that might be single
elements of, say, Strings or might be an array of Strings.  I write a
single function to handle either case and use a `makeArray` function
to handle them uniformly in my code.  Would you suggest that I should

If you typecheck there...

var coll = typeof param == "string" ?
param.split() : param.slice();

You can do that but it's a little ugly. Not horrible, but better
without that.

have a separate `handleMultipleXYZs` function?  Because the original
source of these things is outside my control, using such would
necessitate sprinkling `isArray` checks over all the code that calls
these functions rather than centralizing it in the one function.  Do
you really object to that sort of overloading?

I do, but not so strongly. I don't like seeing that conditional in the
beginning because it is ugly. But it isn't that hard to figure out.

The link doesn't work.