How To Design A Good API and Why it Matters
HTML-код
- Опубликовано: 12 сен 2024
- Google Tech Talks
January 24, 2007
ABSTRACT
Every day around the world, software developers spend much of their time working with a variety of Application Programming Interfaces (APIs). Some are integral to the core platform, some provide access to widely distributed frameworks, and some are written in-house for use by a few developers. Nearly all programmers occasionally function as API designers, whether they know it or not. A well-designed API can be a great asset to the organization that wrote it and to all who use it. Good APIs increase the pleasure and productivity of the developers who use them, the quality of the software they produce, and ultimately, the corporate bottom line. Conversely, poorly written APIs are a constant thorn in the developer's side, and have been known to harm the bottom line to the point of bankruptcy. Given the importance of good API design, surprisingly little has been written on the subject. In this talk, I'll attempt to help you recognize good and bad APIs and I'll offer specific suggestions for writing good ones.
This talk is part of the Advanced Topics in Programming Series at Google.
Google engEDU
Speaker: Joshua Bloch
this guy designed many of the JDK classes (the good ones) and worked at Google. Knows his stuff.
43:08 he redesigned stack as arraydeque.. people still using Stack today (literally 15 years after its deprecated) because the naming.
Slides can be downloaded from this new link: static.googleusercontent.com/media/research.google.com/en//pubs/archive/32713.pdf
"Once you have something that's called a 'set', you know what the operations are. You insert things from [sic] sets, you remove, ..." [23:42]
That's like saying "The operations on an 'integer' are incrementing, decrementing, ..." No, those are the operations on an integer _variable_. An _integer_ is, among other things, the _value_ of such a variable at a particular point in the program. It's a pure value; you can't modify 3, you can only cause a variable that currently holds 3 to change its state so it now holds some other integer. If you want, you can create an integer _object_ that holds an integer and is shareable: you can have multiple references to such an object, so that changes in its state are visible via any of those references. But no one would confuse such an object with an integer.
Sets are a mathematical concept just like integers. What Joshua Bloch is thinking of (and what his Java Collections Framework incorrectly _calls_ a 'set') is actually a set _object_: a mutable, shareable object whose _value_ is a set. Such an object can hold one set at one time, and a different set at at different time.
Here's what I'm getting at. The JCF should have one interface 'Set' that models a pure set value, with no mutating operations, and a second interface 'MutableSet' that extends the first and models a set object, with operations 'add', 'remove', etc. (Similarly, of course, for lists and maps.) Currently, when you're writing some class that contains a mutable set and you want to return a representation of the contents of that set from some method but you don't want to give the caller the ability to reach in and modify it directly, you have to either copy it (ugh) or use 'Collections.unmodifiableSet'; but the latter enforces immutability only at runtime (if the caller tries a mutating operation on the set, an exception is thrown). If there had been two interfaces, you would just have to use 'Set' for the return type of your method rather than 'MutableSet', and immutability would be enforced on the caller statically, at compile time, rather than at runtime.
The general lesson I would propose drawing is that if you're designing an API that touches on an area of mathematics -- set theory, in this case -- try to model the mathematical concepts as directly and purely as you can. Make a particular effort to keep implementation concerns separate. You don't have to eliminate them altogether, but try to tease them apart from the math. (This will also help to future-proof your API. In 1997, it wasn't well known how to efficiently implement completely functional collections, where what would once have been a mutating operation now returns a new collection without changing the original one; since then, through the work of people like Chris Okasaki and Phil Bagwell, we know how to do it, and such collections are available in languages like Clojure and Scala.)
Kotlin has Set/MutableSet, List/MutableList, Collection/MutableCollection and Map/MutableMap where the former are compile-time read-only views on (potentially) mutable versions.
You can get the slides from here.
lcsd05.cs.tamu.edu/slides/keynote.pdf
not any longer :(
www.cs.bc.edu/~muller/teaching/cs102/s06/lib/pdf/api-design
is there a link to the slides, since he ran out of time for the last part?
Funny that this is still recommended watching in 2022 by Google recruiting emails, when a lot of these issues have been obsoleted by IDE usage, JSON, and modern languages like TypeScript. Much more commonly important nowadays is the design of REST APIs.
BTW, code like that at 45:46 makes me 🤢. And lots of Java code I've seen has been like that. 🤮
amazing content
hope you keep update :)
Good job
If he's trolling, he's a master-level player :D
Top notch content.
This is definitely 2007. I've been told not to add comment. Which makes me cry......
Google for the name of the talk. Looks like the deck is available on slideshare.
fantastic!
For anyone interested, we are working on a tool to make API design more efficient, collaborative and robust.
apiengine.io - we are taking early registrations for beta!
I'd just like everyone else who reads this man's comment to understand that he is, in essence, kvetching about someone having the audacity to use red to indicate bad, and green to indicate good.
That's right. It has absolutely no bearing on this video whatsoever.
Well, now i know how not to design API :)