The Shyam » javascript

APIs and what not to do

shyam — Mon, 12 Apr 2010 20:41:57 +0000

APIs seem to be like opinions. Everyone has one, and no two people have the same concept of what constitutes a good one. An API is supposed to be an interface that is exposed for other programs or programmers to use to interact with your code. Except, each API, like an individual, is unique with its own flaws and niceties. A great API is one which reduces the amount of code you have to write when you use it. I personally feel amazing if I can get something done with minimal code. That just screams “GOOD API” to me.

On the other hand, a bad API leaves you feeling dirty, unclean even, as if you are committing grave sins against nature even by just using it. Here are a few common mistakes which end up leaving that bad taste in your mouth (with examples, of course!) :

Bad APIs

These are the worst offenders, the APIs which are supposedly there to make your life easier, but just end up making it more work to use it than rewriting it from scratch. I faced one of the bigger offenders of this one recently when I was working with GWT. I was trying to create a tree structure to represent a navigation hierarchy when it dawned on me.

A GWT Tree is created by creating a Tree object, and then creating a tree item for each node. To append children to each node, you create further tree items and add whatever text or elements you want to it. So to summarize, even if I have a data structure to represent my tree (which in most cases, I do), I will have to traverse it manually, create tree items, tell each one how to render itself and then append it to the correct items. Yuck.

Now consider how JFace creates a Tree (which I consider much more powerful and a nicer API altogether). You create a TreeViewer, set its data source / input. Then, you set a content provider which knows how to traverse your data object and get children / parents. You can also set a LabelProvider which tells it how to render its data elements. End result? Nice clean code that I actually feel satisfied about.

Most of these are the end result of rushed / not well thought out design. Having a concrete use case prior to designing it should have been enough to scream out “Its ugly!!!”. Suggestion to prevent this : write a test / use case for anything you start designing, so you can get a feel for how it feels in action. That should help you avoid a lot of these.

Not fully thought out APIs

This one is similar to the previous one, but I think it deserves section and example of its own. This happens when you almost nail the API, but fail to consider some common uses of the API. The biggest offender of this one I believe is the Java List API.

The two most common use cases I have in Java when I work with lists are
1.) Iterating through them to perform some operation and
2.) Filtering the list to get a subset

The second operation is so common that I get annoyed now that I have to create an empty list, iterate through each one using a for each and conditionally add elements to the new list. Now I realize that Java doesn’t make it easy to pass in functions (check my older article about this) as arguments, but what I really really want here is the ability to do myList.filter(predicate) where predicate is a predicate function I decide, which returns the filtered list with elements matching the predicate.

There are many more such common operations missing on the List interface, but this is the most egregious one I believe. Javascript also gets this wrong, but underscore, a JS library adds a lot of this which makes working with lists and collections a dream.

Misnamed APIs and methods

How many times have you called a method, only to realize that it didn’t really do what you thought it did? Or look for a method XYZ, only to realize later that it had been named YXZ instead. Raise your hands if you have experienced this. For some reason, an apple for someone almost always turns out to be an orange for someone else.

I’ll switch to bashing on JS for this one, underscore in particular. For all the amazing methods that underscore provides in JS, they really have a problem with naming. I ended up looking for a collection.contains method, and ended up finding only indexOf, so I initially assumed that they didn’t have it. I mean, if I look for contains, at best, I will also look for has, hasKey. Browsing through the list of method names, I might have even accepted includes (though it would not have been my first choice). But never in all my life would I have expected it to be include (Yes, that is include, as in singular!). People, what were you thinking????

Liars

The final set of APIs which can annoy (but are easily worked around, just like the previous section) are APIs which lie. These include APIs which don’t do what the function name suggests it does (no obvious example from the open source land comes to mind, thankfully). The other kind is one which is not done with work even after the object is created. Most times, it is the case of a lurking init / initialize method. And if you ever see an interface called Initializable, run in the opposite direction.

Is Strong Typing really needed?

shyam — Thu, 04 Mar 2010 19:36:40 +0000

This is something I have been struggling with for the last few months. I have had people argue ardently that all Strong typing is good for is false comfort and lots of unneeded typing. But I was strong. I was undeterred. I dismissed this as the crazy rants of those JS developers, those dynamic language people who believe that obfuscation and compactness is everything, even at the cost of maintainability. I mean, how could a language where you didn’t even know what was getting passed in in any ways better than something where the APIs are explicit and stop you from making mistakes. A dynamic language could work for a single developer, but definitely not for a team. That was my whole hearted conclusion.

Now, I’m not so sure anymore. Its been 3 weeks since our team made the whole hearted switch. Has it been roses and sunshine? No. But it hasn’t been as bad as I expected it to be. And there are a few reasons for that. But before that, I’ll lay down the pros and cons the way I see them from my (assuredly very limited) experience :

Benefits of Strong Typing :

Errors / Warnings in your editor
Simply put, this might just be the single most greatest benefit of strong typing, and the single reason why most java developers (a lot rightly so) will never even consider leaving the safety of strong typing. While compilation support doesn’t necessarily go hand in hand with strong typing, most people tend to associate Java with it, so lets run with that. Simply put, with Strong typing, your editor can (and should, I mean, if you are not going to get immd. feedback, what’s the point?) give you immediate feedback when you messed something up. Whether this be using the wrong variable name or trying to call a method that either does not exist or with the wrong parameters. Or if you are trying to use the wrong type of object.

To a Java developer, an IDE like Eclipse or IntelliJ is godsend, as it tells you what is wrong in your world and lets you jump to them, gives you suggestions and autofixes and generally makes your life as painless as it can. And it is brilliant, I can tell you that.

In Javascript (or any other dynamic language), everything is fine and dandy for the first 100 lines. After that, it becomes scarily unmanageable. The only way around this that I have found so far is to be super paranoid and write tests for every single line of code. If you can’t do that, stay far far away.
Generics (but this is also a negative, in my opinion, which I’ll get to below)
The idea behind generics is that gives developers some assurances about the types in a collection (or whatever it is you are genericizing). That way, all operations are type safe, without having to convert to and from different types. And you are assured that you will not be surprised suddenly by a different type of object popping up when you least expect it. But there are a lot of issues with them that I’ll cover in the second section.
Ability to follow a chain and figure out what type of object is required at each step
Now this is something I definitely miss in languages like Javascript and Python. The fact that I can trace (in my IDE, note that part) what the type of each variable / method call in an expression chain is simply amazing, especially when you are working with a new codebase. You never have to wonder what the parameter types of the method you are calling are. You don’t have to wonder what methods are available or visible. You just know this information (Again, assuming you are using an IDE. If not, god help you)
Refactoring
The biggest advantage of Strong typing though, in my opinion, is the ability to create IDEs which make refactoring a breeze. Renaming a method / variable? Trivial. Moving or extracting a method? Simple key combination. Stuff which can be extremely tedious and mind numbing are accomplished in a matter of minutes. (Want to know more about these shortcuts? Check out Eclipse shortcuts). This is simply not possible with languages like Python and Javascript.

Disadvantages of Strong typing :

More concise and precise, less typing
Dynamic languages do tend to be more dense, and it is much easier to accomplish in 10 lines what can easily take 50-100 in a language like Java, which is especially verbose. Consider trying to pass in a chunk of code to be executed at the end of a function in both Java and javascript (this is pretty common in web apps and task runners)
Java :

interface Function {
T execute(); // Optional parameters is not easy here :(
}
taskRunner.execute(taskArgument, new Function() {
String execute() {
return "Success";
}
});

Javascript:

taskRunner.execute(params, function() {response="Success"});
No badly implemented generics
This is mostly Java’s fault of getting generics pretty badly wrong. The idea behind generics is sound, its the implementation that is horribly broken. Here are a few things which are wrong with it :
Type erasure : This basically involves the fact that at runtime, there is no way to differentiate between say, a List and a List If you never work with reflection or Guice, then this might not be a problem. But it also is a pain with deeply nested generics and wildcards. I have seen compiling code which blows up at runtime because it cannot differentiate between a Provider and Provider and neither Resource nor Repository have anything in common. Crazy….

Verbosity : Map> myMap = new HashMap>();. Enuff said.

Guice & Reflection : Generics and java.lang.reflect just don’t mix. They just don’t. Type erasure blows away all type information, so you are bound to be using stuff like new Entity which totally defeats the purpose. And don’t get me started on Guice. In guice, normal bindings (non generic classes) look as follows :

bind(MyInterface.class).toInstance(instance);

With Generics involved, they now look as follows :

bind(new TypeLiteral>(){}).toInstance(instance);

What the heck just happened there???
Closures / Functions :
Closures are a form of anonymous inner functions which can have an environment of their own, including variables bound to the scope of the function. The inner function has access to the local variables of the outer scope and can change state. But what it does allow is creating functions, as callbacks or for performing some quick little task in a repeated fashion, easily and quickly and pretty darn cheaply.Java has had a few proposals to add it (http://javac.info/) but it has not passed the review committee yet. And probably won’t for the next few years. So till then, in Java, you are stuck creating interfaces, creating an implementation of it at runtime, passing in variables you need access to in the constructor or through some other mechanism, and generally be in a lot of pain. Thanks, but no thanks.

Super fast JS Testing

shyam — Wed, 12 Aug 2009 16:42:43 +0000

Before I jump into how exactly you can perform super fast and easy JS testing, let me give you some background on the problem.

Javascript is a finicky language (Some people even hesitate to call it a language). And it can easily grow and become a horrible and complicated beast, incapable of being tamed once let loose. And testing it is a nightmare. Once you have decided on a framework (of which there are a dime a dozen), you then have to set it up to run just right. You need to set it up to actually run your tests. Then you have to figure out how to run it in a continuous integration environment. Maybe even run it in headless mode. And everyone solves it in their own ways.

But the biggest problem I have with most of these frameworks is that executing the tests usually requires a context switch. By that, I mean to run a JSUnit test, you end up usually having to open the browser, browse to a particular url or html page which then runs the test. Then you have to look at the results there, and then come back to your editor to either proceed further or fix your tests. Works, but really slows down development.

In java, all it takes is to click the run button in your IDE to run your tests. You get instant feedback, a green / red bar and details on which tests passed and failed and at what line. No context switch, you can get it to run at every save, and proceed on your merry way. Till now, this was not possible with Javascript.

But now, we have JS Test Driver. My colleagues Jeremie and Misko ended up running into some of the issues I outlined above, and decided that going along with the flow was simply unacceptable. So they created a JS Testing framework which solves these very things. You can capture any browser on any machine, and when you tell it to run tests, it will go ahead and execute them on all these browsers and return you the results in your client. And its blazing fast. I am talking milliseconds to run 100 odd tests. And you can tell it to rerun your tests at each save. All within the comforts of your IDE. And over the last three weeks, I have been working on the eclipse plugin for JS Test Driver, and its now at the point where its in a decent working condition.

The plugin in action

The plugin allows you to, from within Eclipse, start the JS Test Driver server, capture some browsers, and then run your tests. You get pretty icons telling you what browsers were captured, the state of the server, the state of the tests. It allows you to filter and show only failures, rerun your last launch configuration, even setup the paths to your browsers so you can launch it all from the safety of eclipse. And as you can see, its super fast. Some 100 odd tests in less than 10 ms. If thats not fast, I don’t know what is.

For more details on JS Test Driver, visit its Google Code website and see how you can use it in your next project and even integrate it into a continuous integration. Misko talks a little bit more about the motivations behind writing it on his Yet Another JS Testing Framework post. To try out the plugin for yourselves, go add the following update site to eclipse : http://js-test-driver.googlecode.com/svn/update/. For all you IntelliJ fanatics, there is something similar in the works.