

Software Libraries don't have to suck - akkartik
http://akkartik.name/blog/libraries2

======
ChuckMcM
Hmm, API design is hard. This is not news, and good api design is a delight.
Various standards bodies have created api 'process' where a potential standard
goes from v0.1 to 0.3, then 0.6, then .8, .9 and finally 1.0. Each step
involving conversations with the consumers and providers of the underlying
capability that the API describes.

Shipping early and often is not kind to API designers. They make some
assumptions, they bake them into the API, some of them are spectacularly
wrong. Except the code has shipped, the barn contains no horses, the cart has
rolled on ahead.

It is perhaps not well understood that being skilled at API design is not
causally related to being skilled at writing code. They can correlate, but the
biggest mistake is to assume that because someone wrote the code they are the
best person to design the API. API design requires an innate understanding of
structure and purpose, requirement and feature. A coder might want an API for
pulling data bytes out of a file, an API designer would consider an API for
moving data from outside the context of the program into the context of the
program without losing semantic coherence of the underlying structure of the
bytes.

Bad API designers get lost into the space of abstract thought, never
converging on a solution. Good API designers use something like Newton-Raphson
to start in the area of the solution and then to iterate into it. All API
designers understand that once a third party has baked in your API to their
code, you change that code at your peril.

~~~
akkartik
Are you claiming the world is working-as-intended?

Since bad API designers so outnumber good ones, and bad APIs get used more
than they should, perhaps we should just avoid the hard problems of API design
by getting users to take a little of the load off?

I consider 'standard body' to be a term of insult, synonymous with 'committee
that designs'. They're great at bolt-on features, bad at rethinking or
expiring designs. So the ANSI C standard still contains overflow-susceptible
_strcpy_ , and Common Lisp ends up with monstrosities like _mismatch_
([http://www.lispworks.com/documentation/HyperSpec/Body/f_mism...](http://www.lispworks.com/documentation/HyperSpec/Body/f_mismat.htm);
<http://dreamsongs.net/Files/PatternsOfSoftware.pdf>, pg 25). All standards
serve to do is perpetuate the canard that we can rely on dependencies while
remaining ignorant of them.

~~~
ChuckMcM
_"Are you claiming the world is working-as-intended?"_

I don't think I mentioned intent. And perhaps that is where we share different
world views. The current state of API design an implementation is an
_artifact_ of the processes used in designing software. I don't think there is
an 'intent' any more than scarcity of a good "intentionally" drives up its
price.

You're blog entry is a call to action to design better APIs but you also want
the rapid evolution and flexibility that you employ in delivering product. My
observation is that good API design practice by its nature takes time, just
like gestating a human child takes 9 months.

So choose, better API or faster code evolution? Hard choice. Most folks are
over in the "faster evolution" camp.

~~~
akkartik
Thanks for the clarification. Hmm, I think I'm still not phrasing this
clearly. I didn't mean to call for better-designed APIs, just unfrozen
interfaces. When things break, make a change and put it out there.

I don't think this has to be a faster/better dichotomy. Imagine a world
without the notion of a stable API. Over time, some interfaces may accumulate
changes and gradually remain unchanged for longer and longer periods.
Eventually they stay stable so long that we can _de facto_ start treating them
like APIs. It seems a perfectly natural evolution.

~~~
ChuckMcM
That is pretty clear, it's the 'rapidly evolving' path. And it works fine
except that you end up with API's with things like

ReadFromStream, ReadFromMemoryOrStream, ReadFromStreamGeneric, Etc. which one
might "want" to say ok the generic is "ReadFromStream" and the various sub-
classes of that can be differentiated within the structure of the first
argument. And after a few months, years (depending on evolution speed) you get
an API that has a number of slightly different APIs, many deprecated, and none
"the best", and someone new comes along and gets frustrated and writes a whole
new library with a new generic API.

And this process doesn't feel too bad to the folks who are primary users but
the secondary users of an API see a lot of churn which keeps requiring them to
rebuild and re-release code that isn't otherwise changed and for them it is
painful.

I'm not sure what your experience is like in this area but my most recent one
has been trying to do 'outside of X11' graphics on an embedded ARM system
running Linux. All of them can mmap /dev/fb0 and do very slow drawing, some
use EGL, some drm/kms, some Wayland or an OpenGL ES library. But all different
and yet all, in theory, running Linux. There are many competing camps making
'APIs' for direct render graphics and they all have their own quirks and
goals.

But there isn't any way for everyone to sit down and say, "Ok, lets see what
is what." and design a reasonably clean and yet extensible API with nice
versioning and a core set of features.

~~~
akkartik
Most interesting. Are all the different options open source? I'd love pointers
to them all, so I can try to put myself in your shoes.

------
mjn
One problem is that making _good_ libraries is hard, and requires ongoing
maintenance effort, ideally motivated effort. My favorite article on the
subject is probably this one: [http://www.yosefk.com/blog/redundancy-vs-
dependencies-which-...](http://www.yosefk.com/blog/redundancy-vs-dependencies-
which-is-worse.html)

------
uiri
The link in the first sentence of your blog post points to
<http://akkartik.name/libraries> when (I think) it ought to be pointing to
<http://akkartik.name/blog/libraries>

~~~
akkartik
Ack, thanks for pointing that out!

------
stephengillie
_programming_ libraries, not _physical_ libraries...

