
Amazingly Bad APIs - Sam_Odio
http://paulbuchheit.blogspot.com/2007/05/amazingly-bad-apis.html
======
mattculbreth
That's a good post. The same thing he describes with Java, with the UML and
the "abstraction" quest, happen on big .NET projects. C# is a fine language if
that's your thing, but boy look out for the UML architects and the patterns.
You'll have a tough time doing things like, "I just want to display a person's
name on the screen" without getting into adapters, visitors, etc.

~~~
aston
The downside is obviously the prolixity. The upside, of course, is that if you
ever want to slightly deviate from the default implementation in another
language, it's a huge pain. If you notice you're doing the same image
transformation multiple times, take the few hours (or few minutes with a
Google search) it takes to get something put together that works exactly as
you want it. Whenever I'm writing in a language with lots of libraries, I find
myself compromising on functionality for the sake of convenience.

And it's not as if Java isn't giving you more flexibility. How do I tweak that
Python code to make the image load faster? Can I get Bicubic interpolation on
the resize? How well do those image objects integrate with other parts of
python, i.e. are they basically just special objects for this library or could
they be used in other ways later?

As a person who doesn't mind writing code and whose IDE autogenerates a lot of
boilerplate anyway, I think I'll take the 100 line hit so I know what's going
on.

~~~
paul
i.thumbnail([220, 133], Image.BICUBIC)

Having everyone rewrite those 100 lines is really inexcusable. Throwing in a
few convenience functions to make the common case simple would not detract
from the "flexibility" one bit. It shows that they gave zero thought to what
people will actually do with the library.

BTW, want to take a stab at writing the "save at different quality level"
code? (since you don't mind writing lots of code) You can post your solution
here.

~~~
aston
I didn't mean to detract from your original point. I think you're right, it's
good to have good libraries. I was just pointing out that there are some
advantages to the way Java normally works. Anyway, as Java's such a popular
language, you can get away with copying other people's 100 lines if you really
need to. A quick Google search turned up an image scaler outright.

By the way, I think it's kind of unfair for you to link to the interface
definitions rather than some implementation for Java. java.awt.Image is
probably just as inscrutable, but at least it does something.

edit: While I'm at it, one point that I didn't quite make clear, but should be
noted is that Image in Java is used all over the place, so its interface is
going to be pretty much targeted at not missing any possible use case. If
you're interested in a narrow-scoped pixel image application, why not use some
Java image processing library? Sun's got one:
<http://java.sun.com/javase/technologies/desktop/media/jai/>

~~~
bootload
_'... you can get away with copying other people's 100 lines if you really
need to ...'_

Owch! that will come back to bite you. Wouldn't it be better to re-write, re-
factor to reduce complexity and get cleaner code?

 _'... think it's kind of unfair for you to link to the interface definitions
rather than some implementation ...'_

because it's the interface that we are stuck with & have to work with

 _'... If you're interested in a narrow-scoped pixel image application, why
not use some Java image processing library? ...'_

because it's not COSHER & I do not want to be locked into using non-free
software ~ <http://wearcam.org/cosher.htm>

~~~
aston
"because it's the interface that we are stuck with & have to work with" is
blatantly wrong. You can use anything you want to manipulate images; don't
feel bound to using the standard Java Image class. To my knowledge, there's no
standard python image class, so there's not even a comparison here.

As to your other points, I'm not sure why you assume copying code leads to
that code being bloated or unclean. Bad assumption. Personal preference on the
latter point, though it's pretty easy to find open sourced libraries.

~~~
bootload
"... I'm not sure why you assume copying code leads to that code being bloated
or unclean ..."

 __DEFECTS __if you cut+paste code from place to place and find a single
defect in the block you have to go and find all the other instances you have
pasted the code.

 __BLOAT __If you cut+paste code it increases the number of lines of code
within the codebase so the LOC increases.

Software development within a startup context is about creating code that is
_"reliable, smaller, cleaner & faster"_. Reusing code is good but not at the
expense of modularity, bloat and defects. Not using _cut & paste_ as a
development practice isn't personal preference, its DEV 101 ~
<http://en.wikipedia.org/wiki/Copy_and_paste_programming>

------
far33d
The problem with over-abstraction is that it makes all specific tasks equally
difficult. In order to make the hard easier, it makes the easy harder. And
that's assuming that you aren't using some slight boundary condition of the
abstraction, in which case even the hard becomes even harder still.

Usually, the first thing you think of (in this case, the way the python is
implemented) is usually best. If you need something more specific, a specific,
instead of abstract, solution is probably better.

<http://www.joelonsoftware.com/articles/LeakyAbstractions.html>

~~~
euccastro
I thought I'd add some nuance to this.

The problem with 'over-abstraction' is not too much abstraction per se, any
more than the problem with 'oversimplification' is excess of simplicity, or
the problem with 'overgeneralization' is too much generality.

Abstraction, simplicity and generality are, in themselves, desirable
properties in a design, since they reduce the bulk of design concepts we have
to fit in our heads. You can't have too much of these.

You can, of course, make things worse for yourself by neglecting other design
goals while striving for a particular one, or by stalling progress in your
project by spending too much time in analysis paralysis.

The decision is not only between less or more abstraction, though. There are
'better' and 'worse' abstractions, as measured by their ability to show what
is important for the client and hide the irrelevant. In Joel's examples of
leaky abstractions, you can say 'too much' is being hidden. I'd rather say the
wrong things are being hidden, or that it's done in the wrong place. You could
conceivably hide 'more' irrelevant details while still letting every part of
your program see what it needs.

To further complicate matters, the fitness of an abstraction for practical
purposes depends on cultural factors. Some powerful abstractions only help if
you've made the investment to learn and internalize a certain way of thinking
about programming. On top of that, you may need to consider the skills and
preferences of your audience.

In the example at hand, if Java needs 100 lines to perform an operation, while
Python does away with 3, it's hard to argue that Java is being too abstract,
or, indeed, more abstract at all. You can say it overindulges in
'abstractions'. But note that the end result burdens the user with lots of
details that are irrelevant to them. That is exactly opposite to what
abstraction is all about.

------
Tichy
I definitely have the impression that many Java developers just love to play
around - they program for the sake of programming, not for the sake of getting
things done.

That said I am not sure the imaging API is as bad as Paul makes it. My guess
is that the jpg-api of Python is more like the "escapeMYSQL"-method in PHP.
The Java API is very general, so that you can plug in different codecs and
encode the image in whatever way you want (JPG, TIFF, GIF, whatever). Can
Python do the same?

On the other hand, only JPG matters for Web development, so the generalised
API might not be much of an advantage.

~~~
euccastro
The Python Imaging Library can handle all those.

<http://www.pythonware.com/products/pil/>

~~~
Tichy
I am not sure why this turned into a Java vs Python thing - there are lots of
"external" Open Source imaging libraries for Java one could use, too.

~~~
euccastro
Well, the original article was quite Java-vs-Python-y to start with.

Anyway, I wasn't arguing; just pointing out the fact in case you were
interested. I wasn't even aware that there was any type of jpg support in the
standard Python library.

~~~
Tichy
Thanks, of course I am interested. I went through the Python tutorial a few
years ago, but dismissed the language afterwards (also because I didn't like
the API documentation). Now I am wondering if that was a mistake...

------
nickb
Anything designed by a committee sucks :(. What do they say "camel's a
racehorse designed by a committee"...

Java, unfortunately, is full of these crappy APIs because it went through
multiple committees.

------
Tichy
No need to stick to the API from SUN, btw., it seems that several other
imaging toolkits are available. For example

<http://schmidt.devlib.org/jiu/introduction.html>

Don't know about the quality, I just yahoogled it.

------
brlewis
Last blog post was about file uploading, with emphasis on image files. This
one uses image resizing as the example. What is Paul working on?

~~~
imp
It's probably a new paradigm of enterprise software that enables clients to
achieve their full growth potential.

~~~
paul
You stole my idea! Are you spying on me?

:)

