Does anyone design api or library code in this way?

Question

I was reading up some things about how to design a library or API well, and stumbled across Joshua Bloch's great talk at Google Tech Talks. Now although I am nowhere near a professional API developer, I think programming a bunch of classes/functions is a similar, although much scaled-down version of the same thing - clear-cut separation of actions, ease and pleasurable use, encouraging clean code, etc.

I was going through some widely used open source Java code and got this idea (nothing new, but just putting it up lucidly...)

Let us take an example pseudo code (or maybe some dialect of BASIC):

1. new label
2. set name 'hello world'
3. set color 'blue'
4. show 'topmost'
5. on click hide

Now inspired by the Java code I would want to be able to do something like this:

1. Label l = new Label()
2.          .setName('Hello World')
3.          .setColor('blue')
4.          .show(zindex.top);
5. l.onClick = l.hide() ;

My question is this:
Does anyone else design APIs starting from pseudo-code like this?

Is it a good idea for something small? Say upto 10 classes each with maybe 10 methods, each method not more than than 5-6 lines code inside it. That is obviously just a rough set of numbers to to show the size of the classes to be designed - nowhere close to a full API and not just a hobby project - a professional package that does something small but does it well.

Has anyone found any serious drawbacks to this approach?

I think the one real benefit is that it forces you to write down your use-cases first.

The other thing is that the nouns and verbs stay simple, enabling your final product to dodge the MultiPhraseAbstractParadigmDesignPatternImplementor syndrome :-D

Answer 1

Yes, this is the way that jQuery is designed, it always ends up returning itself so that you can chain methods like this.

Answer 2

I tend to start with empty classes and methods. Its really a question of top down vs bottom up design.

I really prefer a huge whiteboard sketch though.

Answer 3

This is a fairly common design pattern called a fluent interface. It's common in functional languages and is gaining popularity elsewhere. I first saw it in Scheme.

It's a very convenient and readable idiom, but remember that there will often be times where you actually do want to initialize more than one variable in a single function call. For example, when there's internal state that has to be set depending on a combination of data, or when setting and overwriting default values is costly. So, as with all "patterns", use judiciously and with forethought.

Answer 4

Jquery does exactly this. From http://net.tutsplus.com/tutorials/javascript-ajax/jquery-1-4-released-the-15-new-features-you-must-know/:

jQuery('<div/>', {  
    id: 'foo',  
    css: {  
        fontWeight: 700,  
        color: 'green'  
    },  
    click: function(){  
        alert('Foo has been clicked!');  
    }  
}); 

or for pre-1.4:

jQuery('<div/>')  
   .attr('id', 'foo')  
   .css({  
       fontWeight: 700,  
       color: 'green'  
   })  
   .click(function(){  
       alert('Foo has been clicked!');  
   });  

I've also done similar things in C# generating WPF in code:

new StackPanel {
   Children = {
      new TextBlock { Text = "Hi there", Width = 50 },
      new TextBox { Width = 100 },
      new Border { 
          Content = new ListBox()
      }
   }
};