Harold, Martin and kisses

Elliotte vs. Martin: Elliotte wins

Yesterday Elliotte Rusty Harold showed disagreement with a recent Martin Fowler article. Elliotte basically says (at least this is what I understand) that APIs should be simple to use, but should not be filled with useless methods, such as "List.last()" and "List.first()" and things like that. Quoting:

More buttons/methods does not make an object more powerful or more humane, quite the opposite in fact. Simplicity is a virtue. Smaller is better.

(read more)

Elliotte says that a class with 78 methods is difficult to use. Why would you want a method such as "List.first()" when you can do "List.get(0)"?

I've been reading Martin's article too. He basically says that he "leans to" the "Humane interface", this is, having lots of methods in a class, but he admits that this is harder.

So, what's the best way to follow the KISS principle? What's better? Having an API with a "reasonable" minimum of methods or have an API with lots of methods, making things easy to use?

This is a tough question, and I think nobody can have the final answer. As human beings all of we have preferences, so our answers will always be subjective.

Anyway I think Albert Einstein was right when he said "Make it as simple as possible, but not simpler". That citation applies quite well to the discussion. Following Albert Einstein's advice would lead us to stick with Elliotte's opinion. We don't need an API that makes things simpler than simple. Simple is simple enough. Simpler is more complex.

Simple or simpler? Kisses are idioms, right?

So what makes an API simple? What simpler? Let's try to see an example. Take, for instance, the DOM API for XML Parsing.

Elliotte was not very satisfied with that API. And I also stick with his opinion: the DOM API is not very easy to use. So he decided to build a new API himself:

XOM is designed to be easy to learn and easy to use. It works very straight-forwardly, and has a very shallow learning curve. Assuming you're already familiar with XML, you should be able to get up and running with XOM very quickly.

learn about XOM

So, why is that? Why is DOM not "easy to use"?

Let's make Elliotte answer that for us. At his slide number 9 we can read:

[... the DOM API ...] Just plain ugly; does not adhere to Java programming conventions.
What's wrong with the XML APIs (and how to fix them)

So Elliotte answered our question two or three years ago. A simple API is one that adheres to Java programming conventions (whether those conventions are right or not we don't mind, after all they're just conventions).

A simple API makes indexes start from 0. And run until X.size()-1. That's simple.

So having a List API that contains a "first()" is not simple. It's just "simpler". Having a "last()" method is "simpler" (and thus more complex) than using the simple "get( size()-1 )".

But, for a Ruby programmer, having "first()" and "last()" is really simple. The other way round is more difficult. Each programming language has its idioms, and an API that follows those idioms is a simple API. An API that tends to be "simpler" and make things against the idioms is an API that makes things more difficult. As Elliotte says the more the buttons the bigger the difficulty.

So that's just my opinion: I like simple things, but not "simpler" things (because those are more complex to maintain).

Make things as simple as possible, but not simpler.

Now, I should apply that myself and forget about thinking of using annotations for everything. But, wait, are annotations a new Java idiom? (Mmm, that's more food for thought during the next holidays ;-)).

Any (simple) opinions out there?

Cheers, ;-)
Antonio

Comentarios:

Antonio,
this is also discusses at this blog (not mine): http://www.cincomsmalltalk.com/blog/blogView?showComments=true&entry=3311314085
One of the comments there actually brought up an interesting fact: take a look at java.util.Vector... look closely and you'll find the methods
Object lastElement()
Object firstElement()

Why was it OK for James Gosling (or whoever did Vector) to add those methods and not for Joshua Bloch (I think the Collections API was his brainchild)? I'm not trying a point with this question... I'm actually wondering why this change of mind happened.

Oh... and on the usefulness of last(): I'd also rather write list.last() (or list.lastElemnt()) and get null for an empty list Than:
if(list.size() > 0){
x = list.get(list.size()-1);
}
which is the only code that you can use in production code (unless you like RuntimeExceptions flying around).

Enviado por murphee en diciembre 08, 2005 a las 08:41 AM CET #

I like the KISS principal personally.

Enviado por Jeffrey Olson en diciembre 08, 2005 a las 09:53 AM CET #

Hi murphee,

I think you should ask the first question either to James Gosling or Joshua Bloch.

Regarding the question asking why this happened, well I assume it's a result of natural evolution of APIs. At the very beginning there was no XML in Java, for instance. With the Collections API happened the same. We needed powerful (and simple to use) data structures in Java.

Regarding "first()" and "last()" well, those were just examples. I've been using Java for quite a long time and, to be honest, I've never used "first()" and "last()" except for sorted maps.

Cheers,
Antonio

Enviado por Antonio en diciembre 09, 2005 a las 02:12 AM CET #

We all love simplicity, but what is it?

That is not a simple question to answer.

I am personally very much in favor of Ruby's slightly crowded APIs in the core language classes (Array, String, Object, etc), because they make my programs more simple. I'm thankful that everything I'm fairly likely to want to do with an Array is right there in the Array class.

The idea that aList.first as an alternative to aList[0] is a complication and is difficult to learn, I have to reject based on my experience. The classes we use a lot can have a higher complexity than other classes without getting in our way. They can have more methods with shorter names. We use them so much that we will learn them anyway.

So, a simple API can be difficult to use. The C language can be said to be simple and beautiful because there is so little functionality in the language and standard library. I don't want that kind of simplicity.

Let me try to explain why I like the method "first" in Array, as an example:

It's a common idiom in shell programming to parse command line arguments by popping the first argument in the argument list and using it to set variables until the list is empty. In that context I think that ARGV.first expresses more clearly that we're picking the element that's currently the first one in a list that is changing. I also prefer to use a word instead of numbers, punctuation and parentheses when I can, especially if it's part of an expression with more parentheses. It makes it easier to read (note that you don't need parentheses for a method call in Ruby). I don't know if this makes sense to anybody else. :-)

Enviado por Jonas Arvidsson en diciembre 10, 2005 a las 07:00 AM CET #

XML attributes are often used to store integers and booleans and whenever I try a new XML API I have to write helper methods to read and write such attributes. A humane interface would include these methods in the API. XOM doesn't.

+1 for humane interfaces

Kevin

Enviado por Kevin Lawrence en diciembre 13, 2005 a las 03:38 PM CET #

Enviar un comentario:
Los comentarios han sido deshabilitados.
About

swinger

Search

Archives
« mayo 2015
lunmarmiéjueviesábdom
    
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
       
Hoy