API Design - Matt Gemmell • Hacker News Board

Re: API Design - Matt Gemmell

#21

Post by conradev » Fri, May 25, 2012, 2:32 AM UTC

This is a fantastic article. I'm glad to see that I have picked up some of these rules intuitively, from reading others' code, and studying the design of Apple's APIs. I do have a couple questions though, that hopefully someone can answer.

With the introduction of blocks in iOS 4, some APIs have shifted to using blocks for messaging. What is the general opinion on this?

Also, for components that benefit from an internal state machine - which is best practice to notify objects of a change in state? Delegate messaging, notifications, or just KVO?

Re: API Design - Matt Gemmell

#22

Post by rys » Fri, May 25, 2012, 9:20 AM UTC

Rule #4 is a nonsense. Why should the data you pass to a class to initialise it be publicly accessible on the class afterwards as a matter of course?

Re: API Design - Matt Gemmell

#23

Post by pirateking » Fri, May 25, 2012, 10:25 AM UTC

conradev wrote: post #21

This is a fantastic article. I'm glad to see that I have picked up some of these rules intuitively, from reading others' code, and studying the design of Apple's APIs. I do have a couple questions though, that hopefully someone can answer. With the introduction of blocks in iOS 4, some APIs have shifted to using blocks for messaging. What is the general opinion on this? Also, for components that benefit from an inter…

I enjoy using blocks in provided API, as well as writing some of my own private API with them. The code locality is very nice for many things like enumeration and animation.

As for notifying objects of state changes, all three methods are used. I use NSNotificationCenter if there will be multiple objects who may need to know about it, KVO as glue for the model and the view, and delegate messaging if there is only one object to notify.

Re: API Design - Matt Gemmell

#24

Post by lucian1900 » Fri, May 25, 2012, 10:31 AM UTC

> plenty of the Steve Jobs type of intuitive, delightful, empowering magic

Huh?

Re: API Design - Matt Gemmell

#25

Post by zdouglas » Fri, May 25, 2012, 12:28 PM UTC

sambe wrote: post #9

Desirable qualities Intuitive Forgiving Frictionless Most of this article applies equally well to humans...

+1 (Funny.)

Re: API Design - Matt Gemmell

#26

Post by billjings » Fri, May 25, 2012, 12:44 PM UTC

rys wrote: post #22

Rule #4 is a nonsense. Why should the data you pass to a class to initialise it be publicly accessible on the class afterwards as a matter of course?

This is one of my favorite points of the writeup, because I've been bitten by it repeatedly over the past year.

Not providing a getter for that data means that if the client wants to use it elsewhere, it needs a second home. So now I'm keeping track of not just a HNCommentsView, but also an object holding the HNText and HNUser it's displaying.

Any time an API doesn't expose that data, there's an implicit assumption of, "The person using this class won't (or shouldn't) need to get at this data this way, so I can leave it out." Which makes it extra irritating to me when it's not there and I need it.

Re: API Design - Matt Gemmell

#27

Post by eblackburn » Fri, May 25, 2012, 2:12 PM UTC

I like this. It espouses good engineering principles (tell don't ask etc.) the advice here is in my opinion applicable to most platforms and domains.

Re: API Design - Matt Gemmell

#28

Post by makecheck » Sat, May 26, 2012, 4:46 PM UTC

billjings wrote: post #26

rys wrote: post #22

Rule #4 is a nonsense. Why should the data you pass to a class to initialise it be publicly accessible on the class afterwards as a matter of course?

This is one of my favorite points of the writeup, because I've been bitten by it repeatedly over the past year. Not providing a getter for that data means that if the client wants to use it elsewhere, it needs a second home. So now I'm keeping track of not just a HNCommentsView, but also an object holding the HNText and HNUser it's displaying. Any time an API doesn't expose that data, there's an implicit assumption o…

Like many things it's generally useful but not a law that applies to every class.

Some counterexamples that come to mind...

- [NSImage initWithPasteboard:] (must NSImage retain the original pasteboard and/or its contents for all eternity, in case you want it back, even if it was in some odd format like NSPICTImageRep that probably doesn't match the internal representation?)

- [NSDictionary initWithContentsOfFile:] (must NSDictionary remember the file path for eternity, and/or its contents, in case you want it back?)

Yes, if an initializer is basically accepting things that become properties anyway, it makes sense to expose those properties. But initializer arguments are not necessarily sensible or useful to keep around in all situations.