Designing an API is an art and a science. Many intelligent people have failed. Those who succeed do so by keeping in view the main goal of an API: to annoy the hell out of developers.
My brothers and sisters, to honor that noble-ish pursuit we gather together to enumerate (see what I did there) the Seven Deadly Annoyances of API design. I never thought I’d write a listicle, but at least it has an erudite religious reference in the title.
First, a couple rules: Weâre talking about successful, working APIs here. So things like âit doesnât workâ or âit opens a massive security holeâ donât count as annoyances. Don’t take the word “deadly” literally. And APIs that no one uses are not qualified. No, failed APIs are not annoying, just bad. Here we discuss just the minor things. The minor, hair-pulling, keyboard-smashing, Urban-Dictionary-quoting annoyances we all know and despise.
Many of the examples come from Android, because that’s who most recently has the pleasure of annoying me, but I donât mean to pick on them. They have no monopoly on these sins.
Annoyance the first – trsnss
Yes, name-ification of things is hard. Still, common sense could go a long way. You gotta hand it to the Unix folks for their heroic efforts to save a keystroke – why say dupe when we can save that valuable E and say dup?
Number two is related:
Annoyance the second – makingNamesMuchTooLongToBePractical
Apple, in contrast, gives us gems like
outputImageProviderFromBufferWithPixelFormat:pixelsWide:pixelsHigh:baseAddress:bytesPerRow:releaseCallback:releaseContext:colorSpace:shouldColorMatch:
Vexation number three – Using synonyms
Oh, Android, Iâm looking at you.
Apparently thereâs a difference between a âBlankActivityâ and an âEmptyActivity.â Whatâs the difference? I once knew, but now Iâm drawing an empty – I mean a blank.
Android gives us tool bars, which at some point got renamed app bars, also known as action bars, giving us lovely code like:
   // Set the toolbar as my app bar    setSupportActionBar(myToolbar);
To abbreviate or not to abbreviate. Thatâs apparently not the question at the Googleplex. Por que no los dos? Cross reference getExternalDirectory and getExternalFilesDir. These return two different locations, by the way, because sometimes in a directory you want to store files, and sometimes you want to store⊠I dunno, something else.
Whatâs the difference between a tap and a touch? I have no idea (at least not on a phone), and neither does the Android design team, who also sometimes calls it a click.
Hey, what version are you running? Oh, it’s KitKat. Or is it 4.1? No, maybe it’s SDK version 19… Oh wait, those all mean the same thing. Good luck keeping them straight.
And a final Android example. Want to make a project asset available by URL? Simply put it in the /assets/ directory in your source tree and construct a URL starting with âfile:///android_asset/â. Yep, one is plural, one is singular. One has android_ in front, one doesn’t. Why? Because theyâre Google and they can do whatever the hell they want, thatâs why. What are you gonna do, use FirefoxOS?
Annoyance the fourth – Poor (or absence of) documentation
Speaking of asset URLs, you wonât find out about them by reading the documentation, aside from an offhand mention of it on the WebSettings.setAllowFileAccess method – a method which has zero affect on whether you can access files this way. Yes indeed, the old semi-documented feature.
Then thereâs the Context class. It’s the Kardashian of classes: no one is quite sure what it does, but it’s everywhere you look. No one knows why, but you need it for almost all API calls. So thereâs that.
Want to add a toolbar/action bar/app bar to your Activity? Hereâs how you do it using the backward compatibility library. What if you donât need backward compatibility? Surely thereâs a way to do that with the built in classes? Probably, but you wonât find that in the official documentation.
And speaking of backward compatibilityâŠ
Annoyance the 5.1beta3 – Version incompatibility
If youâve developed for Android, you know. Oh, you know all right. I⊠I canât even write about this. The memories are too raw. Just.. you know.
WHY DOES IT WORK ON KITKAT BUT NOT MARSHMALLOW OR JELLYBEAN?!?!?!?!?!?
Annoyance the 6 – Overcomplimification (easy things made hard!)
Ahh, Fragments, how I love to hate you. Hereâs a real diagram from Android documentation:
But worse than Fragments are Notifications. Check the Android documentation for the section âCreating a Simple Notification.â Just in case they werenât clear how simple it is, they make sure to repeat the word in the first sentence: âThe following snippet illustrates a simple notification.â Care to see this oh-so-simple code snippet?
NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this) .setSmallIcon(R.drawable.notification_icon) .setContentTitle("My notification") .setContentText("Hello World!"); // Creates an explicit intent for an Activity in your app Intent resultIntent = new Intent(this, ResultActivity.class); // The stack builder object will contain an artificial back stack for the // started Activity. // This ensures that navigating backward from the Activity leads out of // your application to the Home screen. TaskStackBuilder stackBuilder = TaskStackBuilder.create(this); // Adds the back stack for the Intent (but not the Intent itself) stackBuilder.addParentStack(ResultActivity.class); // Adds the Intent that starts the Activity to the top of the stack stackBuilder.addNextIntent(resultIntent); PendingIntent resultPendingIntent = stackBuilder.getPendingIntent( 0, PendingIntent.FLAG_UPDATE_CURRENT ); mBuilder.setContentIntent(resultPendingIntent); NotificationManager mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE); // mId allows you to update the notification later on. mNotificationManager.notify(mId, mBuilder.build());
Oh dear, Iâm overwhelmed with the beauteous simplitude!
Just to rub it in, the Android documentationalists follow this up with âThat’s it. Your user has now been notified.â Oh, thatâs it! Wow, and here I thought there would be some code involved, but now that youâve shown me this crystal clear 27-lines of beauty, I feel relievificated. And donât forget to import the three class you need. Oh yeah, and if you want backwards compatibilitude, itâs a whole different set of classes, plus you upgrom your gradle file and and do something else I mean who cares itâs stupid i give up i quit ill be a bartender.
What?
Oh, and donât forget to also copy-paste these 30 lines of XML into a completely different file.
Speaking of which, the final and seventh deadly annoyance of API design is…
7. XML
Enough said.