5 ms·

Amazingly Bad APIs

28 points by Sam_Odio 19y ago

mattculbreth 19y ago
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 19y ago
  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 19y ago
    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 19y ago
      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/ http://java.sun.com/javase/technologies/desktop/media/jai/
      - bootload 19y ago
        '... 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 http://wearcam.org/cosher.htm
        aston 19y ago
        "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.
  - mdakin 19y ago
    Python gives you both upsides (the easy typical case AND the custom arbitrary C/C++ code case). Granted one needs to know C/C++ and not Java. If whatever operation you need is not already implemented by a Python module you can just write those 100 lines of fast C++ code and then call it from Python. As far as knowing what's going on in general you can always look at the Python source code.
  - davidw 19y ago
    One of my favorite API's is Tcl's socket API. The simple case is really simple: set sk [open news.ycombinator.com 80] And you're in business. If you want to do more complex things, you can then operate on that socket, fiddling with all the options (blocking/non blocking, buffering, etc...). The lesson is: make the obvious thing really easy, and give the user a means to access advanced functionality without requiring it.
- bootload 19y ago
  '... but boy look out for the UML architects and the patterns ...' Matt don't let the Architect Astronauts scare you ~ http://www.joelonsoftware.com/articles/fog0000000018.html http://www.joelonsoftware.com/articles/fog0000000018.html
brlewis 19y ago
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 19y ago
  It's probably a new paradigm of enterprise software that enables clients to achieve their full growth potential.
  - paul 19y ago
    You stole my idea! Are you spying on me? :)
- mattculbreth 19y ago
  Whatever it is I can assure you it doesn't involve a database.
- paul 19y ago
  These are common tasks for any website that has images, which is probably half of them. That's why it's crazy that the tools are so bad. I've actually considered writing a photo sharing web site (since there aren't any good ones), but that's not what I'm doing right now.
  - brlewis 19y ago
    OK, I'll relax. Yes, the Java imageio API is painful. I used it to create a function to get image dimensions, but having experienced the pain once I just used a shell script for resizing. If you're still struggling with multiple-image uploads, one approach is to have the user make a zip file; not so hard today, as you can right-click a set of files in your file browser. Also see http://img.ourdoings.com/windows.html http://img.ourdoings.com/windows.html Windows XP also has a web publishing wizard that actually works well once you figure out how to use it. Feel free to reverse-engineer the ourdoings.com implementation of it. You probably aren't going to write a photo sharing web site if you considered it and haven't started yet. You kind of have to be obsessed with it to work through all the details. Since you haven't started you aren't obsessed, and probably wouldn't enjoy it.
far33d 19y ago
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 http://www.joelonsoftware.com/articles/LeakyAbstractions.html
- euccastro 19y ago
  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 19y ago
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 19y ago
  The Python Imaging Library can handle all those. http://www.pythonware.com/products/pil/ http://www.pythonware.com/products/pil/
  - Tichy 19y ago
    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 19y ago
      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 19y ago
        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...
- bootload 19y ago
  '... 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 ...' hmm I thought that would have been a positive attribute to look for
Tichy 19y ago
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 http://schmidt.devlib.org/jiu/introduction.html Don't know about the quality, I just yahoogled it.
nickb 19y ago
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.

28 points by Sam_Odio 19y ago

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 19y ago
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 19y ago
  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 19y ago
    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/ http://java.sun.com/javase/technologies/desktop/media/jai/
    - bootload 19y ago
      '... 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 http://wearcam.org/cosher.htm
      - aston 19y ago
        "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.
- mdakin 19y ago
  Python gives you both upsides (the easy typical case AND the custom arbitrary C/C++ code case). Granted one needs to know C/C++ and not Java. If whatever operation you need is not already implemented by a Python module you can just write those 100 lines of fast C++ code and then call it from Python. As far as knowing what's going on in general you can always look at the Python source code.
- davidw 19y ago
  One of my favorite API's is Tcl's socket API. The simple case is really simple: set sk [open news.ycombinator.com 80] And you're in business. If you want to do more complex things, you can then operate on that socket, fiddling with all the options (blocking/non blocking, buffering, etc...). The lesson is: make the obvious thing really easy, and give the user a means to access advanced functionality without requiring it.
bootload 19y ago
'... but boy look out for the UML architects and the patterns ...' Matt don't let the Architect Astronauts scare you ~ http://www.joelonsoftware.com/articles/fog0000000018.html http://www.joelonsoftware.com/articles/fog0000000018.html

brlewis 19y ago

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 19y ago
It's probably a new paradigm of enterprise software that enables clients to achieve their full growth potential.
- paul 19y ago
  You stole my idea! Are you spying on me? :)
mattculbreth 19y ago
Whatever it is I can assure you it doesn't involve a database.
paul 19y ago
These are common tasks for any website that has images, which is probably half of them. That's why it's crazy that the tools are so bad. I've actually considered writing a photo sharing web site (since there aren't any good ones), but that's not what I'm doing right now.
- brlewis 19y ago
  OK, I'll relax. Yes, the Java imageio API is painful. I used it to create a function to get image dimensions, but having experienced the pain once I just used a shell script for resizing. If you're still struggling with multiple-image uploads, one approach is to have the user make a zip file; not so hard today, as you can right-click a set of files in your file browser. Also see http://img.ourdoings.com/windows.html http://img.ourdoings.com/windows.html Windows XP also has a web publishing wizard that actually works well once you figure out how to use it. Feel free to reverse-engineer the ourdoings.com implementation of it. You probably aren't going to write a photo sharing web site if you considered it and haven't started yet. You kind of have to be obsessed with it to work through all the details. Since you haven't started you aren't obsessed, and probably wouldn't enjoy it.

far33d 19y ago

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 http://www.joelonsoftware.com/articles/LeakyAbstractions.html

euccastro 19y ago
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 19y ago

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 19y ago
The Python Imaging Library can handle all those. http://www.pythonware.com/products/pil/ http://www.pythonware.com/products/pil/
- Tichy 19y ago
  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 19y ago
    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 19y ago
      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...
bootload 19y ago
'... 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 ...' hmm I thought that would have been a positive attribute to look for

Tichy 19y ago

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 http://schmidt.devlib.org/jiu/introduction.html Don't know about the quality, I just yahoogled it.

nickb 19y ago

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.