Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

API Design - Matt Gemmell

mattgemmell.com

Post reply on HN
Print view View original

11–20 of 28 posts

Re: API Design - Matt Gemmell

#11

Post by tumultco »

This is a comprehensive list of many considerations. Top of the list should be to have as small of an API as possible. API is forever. If you expose too much up-front then it increases the surface area of getting things wrong, which developers will be stuck with for a long time or need to deal with eventual deprecations which is fun for no one. Also, more API leads to higher complexity in learning. It is better to see how your API is being used and slowly reveal more functionality as you become confident it is what developers need.

I also believe API should go through a feedback/review processes with peers. Other developers will have used different patterns, have a different base of experience with the platform, and can generally help find common mistakes. So, here's some of my feedback/nitpicks on MGTileMenuController.h :) --

  @property (nonatomic, weak, readonly) id delegate; // must be specified via initializer method.
  - (id)initWithDelegate:(id)theDelegate;
It is very rare for delegates to be required for initialization, and I don't see why the @property for the delegate needs to be readonly? Perhaps an owner would be a better model?

The isVisible property looks like this:

  @property (nonatomic, readonly) BOOL isVisible;
But typically for BOOLs the property is the normal form with a specific "is" getter:

  @property(nonatomic,readonly,getter=isVisible) BOOL visible;

  // N.B. All of the following properties should be set BEFORE displaying the menu.
This makes me wonder what happens if I want to change them later? It seems that they should always be able to be changed, and in general comments shouldn't be required to understand library behavior as they'll just be missed by developers anyways.

  - (NSInteger)nextPageNumber:(NSInteger)currentPageNumber; // zero-based pageNumber
Why would the nextPageNumber not be +1 from currentPageNumber? Also, why do I need to supply a currentPageNumber when it appears currentPage is a @property of the class? Is there a difference between "currentPage" and "currentPageNumber" as their naming indicates there might be one? Also, it might be better to name the method similar to the NSIndexSet convention "indexGreaterThanIndex." Should an NSIndexSet actually be used instead?

  - (UIBezierPath *)_bezelPath;
This method looks like it is private/internal because of a leading underscore, so it shouldn't be exposed in the header. Also, Apple has reserved naming methods with a leading underscore (especially important when you are subclassing!). https://developer.apple.com/library/mac/#documentation/Cocoa...

In general, if the developer doesn't need the utilities, I highly question adding them to the header since you'll be responsible for them for all time.

Finally, why not add the delegate protocol to the header file so everything is consolidated for the developer using the class?

Re: API Design - Matt Gemmell

#12

Post by saddino »

joe_the_user wrote: post #4

Seems like decent advice but perhaps pretty library specific. The only thing I'd argue with is: "Use semantic objects for parameters". I haven't had any trouble passing a null pointer and casting it. Your API is going to be expanding regularly and the more message-passing objects you create, the more message passing objects' definitions you'll have to expand as the API expands.

The best approach I've seen for expanding APIs in iOS is the one Apple tends to use: pass a single NSDictionary of keyed parameter values. The API parameter list never has to change, it's guaranteed to be backwards compatible and you can still enforce use of semantic objects as the allowed values for the new keys you are adding.

(It just struck me that this mirrors the approach Apple used often in Mac Toolbox: passing parameter structs with a version field, instead of modifying the API parameter list itself).

Re: API Design - Matt Gemmell

#13

Post by tmurray »

tumultco wrote: post #11

This is a comprehensive list of many considerations. Top of the list should be to have as small of an API as possible. API is forever. If you expose too much up-front then it increases the surface area of getting things wrong, which developers will be stuck with for a long time or need to deal with eventual deprecations which is fun for no one. Also, more API leads to higher complexity in learning. It is better to se…

"API is forever. If you expose too much up-front then it increases the surface area of getting things wrong, which developers will be stuck with for a long time or need to deal with eventual deprecations which is fun for no one. Also, more API leads to higher complexity in learning. It is better to see how your API is being used and slowly reveal more functionality as you become confident it is what developers need."

This is so, so true. If you find yourself thinking about exposing something because someone might have a use case for it or to provide greater control over some very specific corner case, write it down, file it somewhere, and revisit that when you see how people are actually using your API. Don't mistake all the ways your API could be used for all the ways people want to use it.

Re: API Design - Matt Gemmell

#14

Post by drawkbox »

ebun wrote: post #2

"APIs are UX for developers." This simple statement just changed the way that I think about API's.

I literally paused reading when I read this simply put exact statement. I try to focus on minimal, simple apis and preach it to developers and clients for quick integration and maintenance. Now I have this powerful statement to save hours of explaining mainly to non technical people. I have always thought this but never so crisp and to the point. We need t-shirts. Doing a quick search of Google, it appears a few others have recently stated this as much but it is an idea that should take hold: http://www.kryogenix.org/code/apis-like/

Re: API Design - Matt Gemmell

#15

Post by mmahemoff »

drawkbox wrote: post #14
ebun wrote: post #2

"APIs are UX for developers." This simple statement just changed the way that I think about API's.

I literally paused reading when I read this simply put exact statement. I try to focus on minimal, simple apis and preach it to developers and clients for quick integration and maintenance. Now I have this powerful statement to save hours of explaining mainly to non technical people. I have always thought this but never so crisp and to the point. We need t-shirts. Doing a quick search of Google, it appears a few othe…

I don't think the topic is new per se, as really a lot of software engineering history has been about dealing with the human aspects of development. Even fundamental concepts like object-orientation are grounded in psychology and even before software, there were precursors for this kind of thinking in the way machines and working environments were designed. Josh Bloch's Effective Java is a more recent example.

The difference now is that UX has become a popular, well-understood, discipline. So we have a lot more concepts to take back into API design.

Some of us have been capturing relevant links on the topic on a Developer Experience page (https://plus.google.com/116834904360889286443/posts) and under the #devexp hashtag. We don't have t-shirts, but we do have a logo in need of much love! I'll go add a link to that presentation too.

Re: API Design - Matt Gemmell

#17

Post by iredd »

ebun wrote: post #2

"APIs are UX for developers." This simple statement just changed the way that I think about API's.

I 'got' this a few months a go, and it really does make you reassess what you work with and produce. It applies similarly to dev tools.

Re: API Design - Matt Gemmell

#18

Post by wcarss »

timtadh wrote: post #7

This is a great document. Lots of detail, good recommendations. I recently gave a short lecture on API design and came up with the following "touchpoints" of API design. These are sort of general guidelines and a lot less specific than the article was. orthologonal - Properties and methods should not overlap in functionality. If two methods do sort of the same thing but differently that is a design issue. They should…

I believe that the word orthologonal should read orthogonal.

I don't mean to downplay your points; I agree wholeheartedly with your post, but I actually did a double take and thought I might have been spelling the word incorrectly for some time.

Re: API Design - Matt Gemmell

#19

Post by timtadh »

wcarss wrote: post #18
timtadh wrote: post #7

This is a great document. Lots of detail, good recommendations. I recently gave a short lecture on API design and came up with the following "touchpoints" of API design. These are sort of general guidelines and a lot less specific than the article was. orthologonal - Properties and methods should not overlap in functionality. If two methods do sort of the same thing but differently that is a design issue. They should…

I believe that the word orthologonal should read orthogonal . I don't mean to downplay your points; I agree wholeheartedly with your post, but I actually did a double take and thought I might have been spelling the word incorrectly for some time.

Absolutely. That was a mistake I would fix it but I no longer can.
Post reply on HN