Annoyances of API Design
chickenwing.software
chickenwing.software
outputImageProviderFromBufferWithPixelFormat:pixelsWide:pixelsHigh:baseAddress:bytesPerRow:releaseCallback:releaseContext:colorSpace:shouldColorMatch:
Note that standard formatting is to place each argument on its own line, with the colons lined up, and that Xcode does this automatically, and will autocomplete the entire nonsense. It's fairly disingenuous to line the whole thing up as if you need to type it all out.
Also, this is an API that clearly bridges to C-style data structures. Higher level APIs will have much fewer parameters.
> What’s the difference between a tap and a touch?
In Apple-land, at least, a tap is an action (touching somewhere and releasing quickly, as opposed to a swipe, etc.), and a touch is where a user's finger is currently placed.
I can't see the downside, yet the author of the article acts like it should be obvious.
There exists a type of programmer who will write essentially the same lines of code over and over and over again. If you're this type of programmer, having to type long function names is extremely painful.
There exists another type of programmer who refuses to retype the same thing over and over, so instead uses some technique for reusing that code. If you're this type of programmer then long, descriptive names are preferable.
If I'm reading a variable name and by the end I've forgotten the first half of it's name, the long descriptive name isn't helping me nearly as much as the author might think.
Really, the variable name has a context, and I want to evaluate it within that context. That is, within the function as named, or the class and method, what does this variable name mean.
A good name is short enough to read as a sign in itself, it shouldn't be parsed as a sentence.
The more code reuse there is, the less you might be using the same name, as a sister comment says - but the more names you have, and a lot of long names is really hard to read. So I disagree with sister's "downside" of "it's bad for bad programmers". It's even worse for otherwise good ones who buy into this style. (Or maybe not, maybe they just read differently from me and say Rob Pike who objected "names which are short essays about the thing they name.")
outputImageProviderFromBufferWithPixelFormat:
pixelsWide:
pixelsHigh:
baseAddress:
bytesPerRow:
releaseCallback:
releaseContext:
colorSpace:
shouldColorMatch:
- tableView:didSelectRowAtIndexPath:
- tableView:didDeselectRowAtIndexPath:
I still prefer long descriptive method names though.
These days, I format the method so that each param goes into a newline (after Xcode autocompletes it) and this helps me catch such bugs.
Edit: wrong API! This one does have a pixel format object.
It also tries to be helpful and so doesn't require all parameters. If you don't give it a data pointer, it will allocate memory for you. If you don't give it bytesPerRow, it will calculate it for you. These ought to be separate calls, not all glued together into one gigantic do-everything call.
The verbosity itself is fine, but it's symptomatic of some suboptimal API design behind it.
While it doesn't address everything you're alluding to, I'm a big fan of Swift's nonnull/nullable making its way into Objective-C since some of Apple's APIs don't play well with a nil parameter (e.g., -[NSString isEqualToString:]).
Besides being clear w/o having to dig into references or source, it also makes 'oops, wrong variable order' bugs much less likely to occur (e.g., swapped width and height is obvious using the above, not so much if using positional args).
For instance, the phrase "outputImageProviderFromBufferWith..." suggests that the Buffer concept should have been a separate thing (probably its own class), that OutputImageProvider could be constructed from.
XML's saving grace was that it came with good schemas out of the box, so turning something from XML to, say, a Java object, was not very difficult. It wasn't difficult to use a SOAP service without having to do manual serialization work.
Today though, we are using something that has, at best, extremely weak types, and with schema equivalents that are bolted on, rarely used, and end up relying on humans understanding exactly what the data looks like, just for serialization/deserialization. I guess you can live with that easily if you are writing in a language that has really weak types in the first place, as you'd have to read the documentation anyway (What date format is the field using? Better go read about it), but the moment you try to do something even slightly more sturdy, the process is excruciatingly painful.
Heck, even tools like try to "help" document APIs, like swagger, end up with specifications that chill the bones.
It is as if the web was built for and by people that are absolutely allergic to both specification and types: In a more sensible world, we'd get something like: If the RDS is postgres, then the data format is like this, and if it's MySQL, it's like this instead. But what we have out there in the world is big lists of optional fields that will be illegal, or ignored, or who knows what.
I was a big XML hater, back in the days of SOAP, but the more I see how services are defined today, the better the old rust bucket looks.
TLDR I used to be a big fan of XML, have switched to JSON, and probably won't be going back.
Huh? How do you know what types <a><b c="d"><e/></b><b f="g" /><a> has? How do you transform that into a Java object? For that matter, if you manage to turn this into a Java object, how do you know how to transform it back into XML? What members turn into attributes and which turn into sub-elements?
Or are you referring to XSD, which showed up years later, is not required, and often not used? Yes, XSD grafts typing onto XML quite effectively, but this is a bolt-on just like the JSON approaches. It just turned out to be a widely-adopted bolt-on.
JSON is inherently "schema-less". So this provides us with no grievance.
> something that has, at best, extremely weak types
You provide the reader with nothing that indicates that strong-typing is important for JSON use-cases.
> schema equivalents that are bolted on, rarely used, and end up relying on humans understanding exactly what the data looks like
There are no schemas in JSON.
True, json has no formal explicit schema attached to the data.
However, there is still the ad-hoc informal schema that's defined by what the code interacting with the data does. Because this tends to be poorly specified and hard to get at, it's rather annoying to work with.
You really should try to use SOAP again, you will soon change your mind. I used it a few weeks ago (after about 5 years of peaceful life) and let me tell you - it still sucks.
The problem with SOAP is that, even if it is a standard, every $@%#*! library implements it in a slightly different way, leading to incompatibilities. Maybe it was just my luck, but every time I tried to use SOAP I ended up debugging XML envelopes and whatnot. With REST/HTTP + JSON? Just send, receive, parse, do what you want.
</rant>
What about 'strncpy' versus 'strlcpy'? Or 'vsnprintf'? 'fcntl.h'? 'execlp'? 'EBADF'? 'SIGSEGV'? 'lstat'?
C89 says:
"The implementation shall treat at least the first 31 characters of an internal name (a macro name or an identifier that does not have external linkage) as significant. Corresponding lower-case and upper-case letters are different. The implementation may further restrict the significance of an external name (an identifier that has external linkage) to six characters and may ignore distinctions of alphabetical case for such names./10/ These limitations on identifiers are all implementation-defined."
And I mostly use some form of auto complete so I'm not worried about the effort saved from typing.
shapeEffectSingleBlurFrom:withInteriorFill:offset:blurSize:innerGlowRed:innerGlowGreen:innerGlowBlue:innerGlowOpacity:innerShadowRed:innerShadowGreen:innerShadowBlue:innerShadowOpacity:outerGlowRed:outerGlowGreen:outerGlowBlue:outerGlowOpacity:outerShadowRed:outerShadowGreen:outerShadowBlue:outerShadowOpacity:hasInsideShadowBlur:hasOutsideShadowBlur:
More generally, a long initializer (or class method that returns an autoreleased object) is a fairly common pattern in Objective-C because it provides a common piece of code that all other initializers can call. There is usually some more obvious and convenient choice available, to avoid calling the horrible method directly.
As with all metrics, that can be gamed. Would
s:o:b:iGR:iGG:iGB:iGO:iSR:iSG:iSB:iSO:oGR:oGG:oGB:oGO:oSR:oSG:oSB:oSO:I:O:
There go all my Unix commands! (OK, that is an uncharitable interpretation—changing `mv` to `move` wouldn't overflow a tweet—but it does indicate, I think, that it's not always obvious when an abbreviation is reasonable.)
I dunno; Tim Berners-Lee has said that his single biggest mistake was including two slashes in URLs (as in http://news.ycombinator.com, as opposed to http:/news.ycombinator.com). (I can't find any better citation for this than http://www.plughitzlive.com/theupstream/298-creator-of-the-w..., unfortunately.) I think that one shouldn't underestimate the apparently negligible impact of an extra character or two, if there will be millions of people typing those extra characters potentially many times a day, over the course of decades or centuries.
(Actually, now that I read your post more carefully, you say that `mv` should be aliased to `move`, meaning, I assume, that `mv` would also be available. I am still unsure about that, because most people would never bother to learn the short version—witness how many people don't know keyboard shortcuts for their most commonly used programmes—but I guess the experts would, and that, perhaps, is enough.)
That fits into my belief that more readable (move instead of mv) is better.
http://library.fora.tv/2009/10/08/Next_Decade_Technologies_C...
He wasn't even saying that the // should be a single /, he was saying that the : at the end of the protocol identifier is already sufficient. He wanted something more like:
http:news.ycombinator.com/I'm not saying that the method name in your example makes any sense, it's definitely insanely long... But the Apple API mentioned in the original post is OK in my books because it's a rarely used initializer for a low-level object. It essentially wraps a raw C pointer into an object, so of course it needs all that metadata about what the pointer is! Putting the same data in a struct wouldn't save any typing.
Hey now, I do! But I'm convinced that I'm subconsciously some kind of masochist, so that's probably not proving you wrong.
I roughly divide naming problems into 3 areas mentally. Most commonly used commands(/functions/identifiers/...), commonly used commands, and rarely used commands.
Most commonly used commands are things like ls or cd or mkdir. Due to their usage frequency, an intermediate user will remember these by heart, and mentally substitute their long forms whilst reading them out. Technically we could assign these to even shorter codes, but then they would loose their mnemonic value.
Preferably they would also have a long-form alias to provide a certain amount of easing into them. (list-directory, change-directory, make-directory)
Commonly used commands should not be abbreviated as readily. The few extra characters required to type them are usually well worth the additional clarity. Pythons .deepcopy() is a good example. It copies a data structure and its sub-structures completely. .dpcp() would be a lot harder to remember given how often it is used.
It should be possible to alias these to shorter versions as well, should someone have to use them frequently. Auto-complete functionality may also reduce the amount of memorization necessary whilst typing these in.
I personally think emacs handles these two cases very well, with it's quick chords that need to be memorized but provide speed, and calling commands by name via M-x which provides ease of use.
Then there's the rarely used stuff. These names may get very long if they are to be descriptive (ncursescplusplusmusicplayer), which means that they, or parts of them should probably be abbreviated (nccppmp, or preferably nccpp-musicplayer). Runs of abbreviated words should not become too long, 3-5 characters being the maximum. Past that length, it becomes hard to remember which characters one has already typed. (ncpmpp? or nccppmp?). Past that sensible chunking through full words or hyphenation may become necessary.
I do think these are sensible rules of thumb, but then they are rules of thumb, and there are most likely thousands of exceptions to them.
> Preferably they would also have a long-form alias to provide a certain amount of easing into them. (list-directory, change-directory, make-directory)
This reminds me of MS Powershell. `Set-Location` is the command for changing to a new directory location, and it's also abbreviated (aliased) as `cd`. Similarly with `ls` and many other commands. Powershell scripts often have the full forms of the commands, while in the shell itself you get the convenience of the shorter commands.
1. You want to make it easy to type/read. 2. You want to make it descriptive. (conflicting with #1) 3. You want to make it consistent and unique. 4. You want to make it compatible with older APIs. (conflicting with #3) 5. You want to make it unambiguous. 6. You want to make it flexible/amenable to future changes. (conflicting with #5) ...
etc, etc. It's just impossible to meet all these requirements with developers that live in a different time and space.
The main issue with most APIs boils down to documentation. Document it well, and it will largely be usable. This means everything from cross-references ("If you are trying to do X, ThisOtherMethod may be a better fit") to examples, and also extends to the API itself (good naming, and discoverable methods). Most developers using your API do not live in your API -- they live in their application domain. So you need to put effort into ensuring jargon is explained, the API is discoverable, and basically they can use the API easily, and get on with their application.
I really like the idea of thinking of API design in terms of Developer Experience (DX), in the same way that user interface designers consider User Experience (UX) about much, much more than simply the layout and colors.
And a simple, easy-to-use API will also be comparatively simple to document. If you're at the point where writing documentation is hard, that's strong code smell that something is amiss.
Personally I'm in favour of long and descriptive names. I'm not afraid of typing. But since I'm writing in C (mostly embedded stuff), I'm not in the mainstream of the C community with my preferences. Sigh.
I actually started when Fragments were being introduced. Now that was a nightmare. The backwards compatibility was a red herring. The real problem was that Fragments were a poor practice, unsuited for many apps and teams... but Google played them out as The Next Big Thing. Today it's happening with Material Design.
Anyway, Fragments are a nightmare. I learned them, I used them, and if I have to use them today I would still need to open that tutorial I have saved somewhere. That is one ugly solution if there ever was one.
I think that this is an underrated question. I am not a programmer, but a mathematician; I will write from my experience in that field.
I was trying to understand a paper which used horrible, ad hoc notation that obscured the simple ideas at its centre. I invented a new, harmonious notation that beautifully revealed these simple ideas, and wrote a paper using it.
The notation was beatiful and harmonious as long as you were its inventor, and it was the most recent thing that you had been thinking about. Now, when I go back and read that paper … I think "wow, this horrible notation obscures the simple ideas at the centre of the paper."
Incidentally, I still think that the notation is better than the original; but the main thing that I've learned is to do it yourself before you complain about what someone else has done—after which (a) you'll have a good implementation and won't need to complain, or (b) you'll feel much humbler and won't want to complain.
Incidentally, writers have been doing this for years with drafts and editing. We definitely need to do that with our APIs and designs (aka. more incremental refactoring).
Not with APIs we've shipped. Then it becomes breaking changes that appear pointless to others. Even when it's logically worth it to go back and fix APIs, it's rarely worth it practically. If no one is using your APIs, then do whatever. If your APIs are popular, you might find yourself in "version next" limbo like so many major projects that redesigned and couldn't convince their users to follow.
To be fair to allengeorge's analogy, writers also rarely edit written works that have already been published.
Also - don't judge MS' love of XML too much, without it, we wouldn't have gotten XMLHttpRequest. :)
True, XMLHttpRequest was good for the world. My distaste for XML generally stems from some particularly bad experiences I have had working with XML configuration files meant for humans to modify and some particularly poorly-implemented tools for working with said files. :)
1 Using the wrong sort of approach for your api eg using a basic REST when the obvious paradime to use would be a Queue.
2 Documentation only comprehensible to insiders who all ready know the system backwards ( I am looking at you Google)
Liberal application of the WTF test is critical[1].
As the author of the api, you yourself will be too close to it to judge fairly. Poorly named functions and over-complicated architecture will appear perfectly reasonable to you if you don't seek outside opinions.
"dup" is short for "duplicate", a saving of 6 characters, not "dupe", which means to deceive or fool.
Glad to see "naming things" made the top of the list. Names that are readable and sensible can be remarkably hard.
TL;DR api design is hard because these are the programmers we write api for. Never happy, can't grasp the basic of the platform they're using, won't read any documentation to save their lives and expect all code to come to them magically perfect as if formed in a vacuum and not having a back-compat history.
That makes no sense. Yes, version X+1 is incompatible with version X. That's why we upped the version number!!!
I wonder if author never had to deal with API/Service that changed and was poorly or unversioned. Suddenly and mysteriously breaking things.
Crockford said, "Changing an API is an act of violence." An API designer should think long and hard before breaking backwards compatibility: usually it's not necessary.
So yes, it's annoying when the next android release is out just as you're finishing your app, your code no longer works and you'll have to rewrite parts just because, while not receiving much benefit.
It's annoying as your application now likely have to support multiple versions of the API as well.