Good afternoon, everyone. Welcome to API Design for Cocoa and Cocoa Touch. My name is Ali Ozer. I'm the Manager of the Cocoa Frameworks team at Apple. OK. So first, there's lot of you here, let's just make sure we're on the same page with regards to what we mean by API. Now, I looked it up. API turns out to have many meanings.

But we're not here talking about Active Pharmaceutical Ingredients. We're not talking about Armor-Piercing Incendiaries. Definitely not the American Pirate Industries. And it's not the American Pain Institute. Now, these all sound like fun topics for talks, but this is not what we're covering. Instead, we're talking about Application Programming Interfaces.

Now, APIs, Application Programming Interfaces, are very important because they allow your code to interface with the system, you know, let you use the facilities of the operating system. But well-designed APIs go much further. They make you more productive. When you're using well-designed APIs, you don't have to look at documentation for every single API. You've learned how the APIs work in general. You can predict how they're going to behave. Well-designed APIs allow you to leverage existing code. Not only can you reuse something, you can go ahead and extend it to your own needs.

Well-designed APIs also let your write code that works as the user expects. That's because well-designed APIs set policy. And by using these APIs, you make apps that, for instance, do the HI guidelines correctly, so the user is happy because your code works like other code. Now, APIs live for a long time so that's why we consider API design very important. Once we've put an API out here and it's adopted, it's very hard for us to get rid of it. So, if we made some mistake, it takes a while to correct that mistake. And one final factor is that API design is UI design for developers.

So, just like Apple takes UI design of its software and its hardware very seriously, we also take API design very seriously. Here are the five factors we consider important when we're designing APIs, and the talk is going to cover, it's going-- the talk is going to have these five sections covering these areas.

Each section is going to start with why these areas are, these factors are important, and now I'm going to give examples of how these factors are reflected in our APIs, and how you yourself can also use these-- use these factors in your own APIs as well. Now, this talk assumes knowledge of Objective-C, and you've hopefully programmed a bit in Cocoa or Cocoa Touch. A lot of the examples I'm going to use are from Foundation, since it's a common substrate to AppKit and UIKit.

However, in some cases, we'll also use examples from AppKit or UIKit as well. OK. So with that, let's begin to our first section which is consistency. And the main topic in this section is naming conventions. Now, I'll just cover some of the naming conventions we use in our APIs.

Now, why is consistency important? Well, as I said earlier, it eliminates the need to refer to documentation for every single API. You can read about the general guidelines, the general rules, the general philosophy, and now you don't have to look up every single API to understand what it does or what other APIs there might be with it.

Consistency also allows different subsystems to plug-in to each other more easily. You know if you get one Objective-C API from someone and another one from someone else, with this consistency, it should work well together. And finally as, well not finally because there are many, many reasons why it's important, but one other way it's important is that being-- having consistent APIs actually can improve performance as we'll see later.

OK. So let's dive into naming conventions. And the first thing I want to talk about is naming of classes. I'm sure many of you have seen some of the classes we have in our APIs: NSString, UIView, CLLocation, et cetera. And typically, class names are nouns. And one thing you'll notice is that we use prefixes. Now, prefixes protect against collisions, and they also differentiate functional areas. A name like view or location is highly generic.

It's possible that two different developers might use the same name. But in addition, using the prefix like CL allows you to immediately recognize that this class comes from Core Location. So in your own designs, in your application, you don't have to use prefixes since you're managing the whole namespace, but it might be a good idea for you to use prefixes as well in which case I recommend either using three-letter prefixes or maybe even more complete longer prefixes for your class names, where it may be it's the name of your company.

Method names, you've undoubtedly seen many methods if not before during this week. Here are some examples. With method names, we focus on readability. For instance, the name "is Editable" there. We put the "is" in there as a general rule because it makes it easier to read, myTextField.isEditable. That reads very naturally. Now, some other things you'll notice here. We use camel case.

What camel case means is the subwords inside our names are actually capitalized. We don't use underbars or anything like that. We actually use uppercase letters. And one other thing you might notice is we choose clarity over brevity. In some cases, our names are not short and we also name all the arguments. Now, I'll talk about these last two now.

So, here's an example method from NSMutableArray removeObjectAtIndex. You might be wondering why all those words. Well, this method is trying to communicate to you that removes an object at an index, so the argument is an index. In fact, we have another method called removeObject which removes an object.

So you can immediately see that these two are distinguished by those words, and it's really clear what each one does. So, those of you wondering why isn't there just a method called remove, well you can now understand why that the method remove would be ambiguous in the presence of these other two methods.

Remove by itself just does not communicate either one of these. And for that reason, we often try to name, you know, with a noun what the argument is about. Naming all the arguments. Here's a method that's not the longer method names in our frameworks. It comes from NSBitmapImageRep, in AppKit.

You can see all the keywords I'm talking about, you know, the pixelsWide, pixelsHigh and so on. Now, here's a secret, but I don't want you to take it out of this room. In fact, you should forget about it after the beer bash wil help with that. I want you to forget about it after you see it. But you can create a method name like this where you actually removed all those keywords. But we don't want you to do that. As you can see, you immediately start losing, you know, some of the what-- you're trying to communicate.

When you're using this method in code, here's what this looks like. You know, you have all these numbers like 32 YES, NO, 0. Without those names, you know, really this will be lot less clear. In fact, let me give you a concrete example. Back about year 2000, we're experimenting with Java and, you know, a lot of other people were a lot of crazy kids.

But we didn't inhale.

Anyway, so here's what this-- and we have this class method actually existed in Java as well. Here is what it look like. New NSBitmapImageRep, and as you can see, you immediately lose all what all those arguments mean - 32, true, false -- you know, you have to go and look up what this means. So, this is the reason why those arguments are important. OK. Naming accessors, getters, and setters. Here are some examples:- color, setColor, isEditable, setEditable, so on.

Now, one thing to note, as I mentioned earlier, for boolean properties that are adjectives, we use "is" on the getter. So, it's "setEditable", but the getter is "isEditable". Another thing you might notice is that we do not embellish the getter with "get" or other verbs. So, for instance, the color method is not called "getColor". It just reads better to have it be "color". Another example is we don't put words like "compute" on the accessors.

For instance, the last one here, even if the thumbnail image is computed, you know, when you ask an object for its thumbnail image, even if that object computes the thumbnail image, it's usually not interesting to communicate the fact that it's being computed. Just have the property, call it ThumbnailImage and that's good enough. Only in the cases where it is important to communicate that or distinguish it would you want to put those words in.

Now, there are some acceptable uses of "get", and that's one case is when we use, we use get on accessors that return values by reference. For instance, the NSData method getBytes: which returns an arbitrary number of bytes given the range argument, it really needs a buffer so to get method.

Another example is this method from UIBezierPath which returns three related arguments, three related properties at once. In this case, we actually have a get method that returns three different values. They are all by reference. You'll note that the caller can pass NULL in for the arguments they don't want in such cases.

For accessors, the simple accessors, you can certainly go ahead and use @property and we encourage that whenever it's possible. You know, our accessors in this case would look like this, property (copy) UIColor *color. For the editable one, we have a special getter because @property does not know about our rule about putting "is", so you might have seen this in our APIs where we specify a special getter. Now, let me talk a bit about functions. Function names you probably seen a few. Here's what they look like. Typically, for functions, the rule is to use a framework prefix followed by the type or functionality area, and then followed by whatever is happening.

For instance, CFRangeMake, CGPathAddLines. And the common prefix allows easier searching, sorting, et cetera. Enum values and constants are very similar. Here are some examples. Now, we also have sometimes common suffixes. Notification is one of them. We use that for NSNotification contants. Key is another one. That's for symbols that are dictionary keys.

Now, one thing to note about functions, enum values and constants, and it's actually true for some other APIs, our naming conventions have evolved over time. So, although we have some examples of, you know, great naming, which follow our conventions, you will also occasionally run across names that are not that great.

These are mostly some of the older names that we haven't either had a chance to deprecate or we're just leaving it in there for old time sake. You can see some examples here. So, not everything you run across especially in some of the older APIs may be correct but, you know, in general, for new APIs, we definitely follow the latest conventions.

Do not abbreviate arbitrarily. Here is a fine-looking method, which is maybe a little too wordy, but you know, as I said again, there is value in that. You might make it just a little bad by arbitrarily abbreviating point to pnt, you know, setFloatingPntFormat, OK. I mean this generally help you because Xcode usually helps you at typing. Or you can make it really ugly by removing all the vowels out of it, if you're a vowel hater.

But you know, we don't recommend this. So, the first one is really the best one here. Now, there are some acceptable abbreviations though, and it's good to be consistent. Our documentation lists some of these acceptable abbreviations: alloc, dealloc, et cetera. There are also commonly used acronyms such PDF and USB, and we recommend you use these. Because if you went ahead and spelled out portable document formats, some people might not even know what you're referring to. You know, people are so used to terms like USB and PDF, so it's best to stick to them.

It's also good to stick to consistent terminology. Earlier, I gave you the example of remove, you know, maybe one possibility is, hey, instead of remove objects, let's use delete, and instead of remove this way, let's use some other term. So, you know, there might be a tendency to look in the source and come up with synonyms. There are a lot of great synonyms. You know, vaporizeObjectsAtIndex, sounds great.

However, it really does make APIs less predictable, so it's, you know, good to stick to consistent words and use more descriptive words to describe your functionality. And avoid names that are ambiguous. You know, at first glance, these names don't look so bad, but sendPort, is that a method that sends a port or is that a port used for sending? displayName, is this a directive to display a name or is it name used for display? Center, is that a verb or is it a noun? It turns out center is a verb in AppKit and a noun in UIKit, so there's one we missed out of the gate.

So, it's good to try to disambiguate these names and choose a little more clear names. Here are some suggestions here. One is this portForSending. localizedNames is actually one we do use whenever we can. And a middle, maybe center as a noun, middle might be a better term, we don't use it, but maybe we should consider. And let me talk a bit about Block naming. Blocks, as you know, are new in Snow Leopard and iOS 4.

Block itself can be ambiguous because Block as a verb is like block, you know stop, block processing. So, we try to be careful with that. So, we use the term Block only in generic cases such as enumerateObjectsusingBlock. But in other cases where we can have more descriptive names, we have come up with a list of names that we use.

For instance, indexOfObjectsPassingTest, a Block that returns a boolean that cites or testing is a test. We also have Comparator, handler, completionHandler, ExpirationHandler, et cetera. So, these are some of the terms we are using to describe blocks. OK. So, the last item I want to discuss in this section is object ownership.

Now, most of you are probably familiar with object ownership rules in Cocoa and the memory management rules. Object ownership is not transferred across calls, and the only methods that actually do are exemptions to this rule are methods whose names begin with alloc, new, copy.mutableCopy or the retain method. So, what this means is whenever you're looking an API, you never have to ask the question, do I have to release the results from calling this method. And similarly, if you're designing your own API, you have a good guideline.

Now, there might be mistakes in APIs especially if a subsystem was designed without API guidelines in mind, maybe it's an internal subsystem of your application. And if you're on the Clang Static Analyzer, it will mark these erroneous names and give you warnings that you're over-releasing an object or you're not releasing it enough.

We do have some attribute, a decorator you can add to methods for this purpose. For instance, if you had a method name, full name that erroneously returned and retained object, you could put NS_RETURNS_RETAINED on there to sort of describe to the analyzer, hey, this returns your retained object.

However, please use this only for Static Analyzer's purposes. You know, do not use it to define bad APIs or just iffy APIs. We intend not to have any APIs, you know, in this system that use this, for instance. If we did, that would be an error and we'd want to fix it.

OK. With that, let's get to the performance section. In here, we're going to talk about Impedance matching, I'll describe what I mean by that, mutability, and concurrency. So, first of all, why is performance important? Well, you know, it seems like that's an obvious question. Users love it, you know, when the applications are fast in response, so that seems like a clear one. But another reason performance is important is that even though an application might seem responsive and fast, maybe it's not fast enough or maybe it's not doing things fast enough where it's using more power than needed.

So, being especially focused on performance, you know, making sure you're getting everything as fast as possible can improve battery life and make users happier. So, let me talk about impedance matching. Impedance matching, to describe what it means, it's a term, I think, from electrical engineering where it's talking about input and output connections, and it's done in such a way that the power is maximized, the throughput is maximized. So, it's basically a term that, you know, where you can connect things together with highest efficiency. You might think of it as plug and play, really, easy plug and play.

Now, what I mean here is this concept of using small number of basic data types in APIs, and not having redundancy. That improves consistency. You can plug things together more easily. Code fits together more easily. In addition, it eliminates the need to do conversions. If you have two different representations for the same concept, every time you cross an API boundary, you have to do conversions on those, and that just reduces performance. So, for to this end, we have a small number of basic data types for strings. You know, we use NSStrings everywhere, in all API for strings.

NSDates for dates. NSURLs to represent file paths. For ordered collections or association tables or map tables, we use NSArray, NSDictionary. There's also NSSet, but it is used less commonly in APIs. In addition, we have this other higher level types, UIColor and UIKit, NSColor in AppKit, and types for font and image as well. So, I recommend that anytime you want to represent an image in your application or in you API, you use either UIImage or NSImage with regard to UIKit or AppKit, and there are few other types that fit here.

Now, not all basic data types are objects. You might know that we have some C types in our APIs as well. For instance, NSInteger and NSUInteger. These are actually simple typedefs on top of int or long. CGFloat is another type like that. It's either a float or a double.

Now, we do have an NSNumber type. It's an object to represent numbers. But you've probably have noticed that we do not use NSNumbers in our APIs to represent numerical quantities, we only use NSNumbers to wrap these basic types when necessary, for instance, when you're putting them in dictionaries or arrays.

Now, we also have some struct types. And for widely use types, you know, things they are using all over the place where abstraction is not important, it's not valuable, it's OK to use structs. We have four widely use structs, points, ranges, sizes, and rects. Consider this point, you know, CGPoint, it's got X and a Y.

We have, you know, we do not pretend that anybody will want to extend CGPoint, nobody is going to want to subclass CGPoint. We have a bunch of utility functions and that's good enough. It's OK for you to go in there and group the X and the Y values, you know, it's OK. It's a public struct, we all understand it, it works well, points aren't going to change. With that in mind, structs are OK.

Structs are good because you can, you know, stack allocate them, and you can use them, you know, pretty flexibly. Now, once upon a time when we were designing some of the basic types, we made the mistake of designing the color type to be a struct. So, it was basically a struct with RGBA, and we quickly realized our mistake, you know, and color is much richer type than that. You know, you have different color representation, CMYK. You have color matching information. So, we could quickly dump that idea and switch to a color object. So that was an example where our struct is not OK.

Now, so far, I've been start talking about reducing a number of types, you know, et cetera, but then I'm also talking about sometimes multiple types that seem equivalent and that seems to violate what I'm saying. So, you know, what's up with CGPoint and NSPoint? Why do I have two types to represent points? Well, those of you working on UIKit probably have never even come across NSPoint because that's an Appkit concept. NSPoint was the original type for NSPoint in Appkit. CGPoint was added later.

In fact, we have made the two equivalent in our 64-bit by making them the exact same typedef. So, for all purposes, these two should be considered equal when you're working in Appkit. And in UIKit, you only have CGPoint. How about NSInteger and NSUInteger? These represent signed and unsigned integer value.

Why do you we have these? Why don't we just use int? Well, our API is used to all the in terms of ints or unsigned ints, but then when we moved to 64-bit on the desktop, we decided to add these typedefs to sort of abstract that away. So, all our APIs are not in terms of NSInteger or NSUInteger, and these are defined to be int or long as needed by the platform.

So again, these are just basic types on those and they are just simple covers. And finally, the CFStringRef versus NSString. Some of you might have played with Core Foundation, used the CFStringRef type for instance, and you might be wondering why do we have two types for strings. Well, it turns out these two types are actually totally equivalent.

You can just typecast between them, no conversion is necessary. The reason we have CFStringRef is to satisfy the needs of very low level implementations that do not use object-oriented programming. For all object-oriented implementations based on foundation or above, use NSString. It plays much better with the object-oriented environment. And it's also on the desktop, especially. This is important. It's garbage collection ready out of the box. So, we refer to this relationship between these two types as toll-free bridging. And this relationship also exists for CFArray and NSArray or CFDictionary, NSDictionary and also a few other types.

OK. So with that, let me talk about mutability. Now, mutable means changeable, sort of like the term "mutate." Many objects are by nature mutable-- only mutable, for instance, NSWindow or UIScrollView. It's got many properties that can change, and it's a changeable object, you can't even think of it as an unchangeable, immutable object. But then there are other types such as strings or colors that can be considered in immutable forms and these are usually value objects. And what I mean by a value object is object whose important characteristic is its value not its object identity.

If you have two strings and their contents are both "hello", you would consider those two strings to be equal, right? So, those are value objects. And in those cases, the immutable approach makes sense. And in some cases, having both a mutable and an immutable variant also make sense. An example is NSString.

If you have an immutable NSString, here is how you would append to it, you have your string, you call stringByAppendingString and you get back a new string that has a result. If you have an NSMutableString and you want to append to it, you would just call appendString and it just modifies that sting in place.

So, looking at that, you're like, "Hm. Mutable string seems more efficient here. We don't have to create an intermediate object. Why do we even have the immutable version?" Well, there are some reasons and actually performance is one of them. If you have a string which has five characters in it like hello and you know it's never going to change, the storage for that string can be very optimized. It can store those five characters in its base object. In fact it doesn't even have to create another malloc block for instance. This also yields to simpler implementation. No mutation is needed. You don't have to keep track of all sorts of editing state.

This yields to thread safety. You know, if you're not changing, you can be a lot more thread safe. And this also allows for easier analysis of program logic. If you have an object at point A whose value is hello and it's immutable, you know that later at point B, it's going to have the same value, so that makes some things about your program easier to understand.

OK. Now, which one to use in APIs? For instance, let's say you're a window or a button and you have a title, here's what your API could look like. NSString title to give you a new title, you know, the callers exactly give you a new title. Or you can have an API like this, NSMutableString title where the expectation is that if somebody wants to change your title, they basically reach in there and mutate that string. As you probably realize, this latter is not what we'd like. We almost always recommend the immutable version; that's because sort of having immutable title and reaching in there to change it feels like you're totally breaking the encapsulation of a window or a button object.

However, oh, and by the way, this is-- if you're using properties, which as I said is usually, you know, good idea, this adheres to the way how you would declare this property, property (copy) NSString*(title). Now, there are few exceptions to this. For instance, there's an NSAttributedString class. It has a string method, however, its subclass NSMutableAttributedString has a mutableString method. And this method, just because it's so special, it returns NSMutableString value and has the word "mutable" in the name actually expects you to mutate that.

It's ready for you to mutate that. So, this is, and in this case, when you mutate that string, the containing mutable attributed string, it sees the changes and takes appropriate action. So, these exceptions are almost always going to be named with the word "mutable" in them one way or another to make it clear to you that yes, this is OK to mutate.

OK. Let me now talk about concurrency. Now, concurrency is a way to achieve higher performance on multi-core machines. As you know, on the desktop, we're adding more and more cores instead of cranking up CPU speeds. So, being able to run things concurrently means you can achieve higher performance.

Now, we've-- you know, all along we have various ways to do concurrency -- we had thread objects, we had runloop objects, we had notification queues, and so on. But now we have a way to represent even more granular, smaller grained work, and blocks are of course that tool. Blocks are a good fit for presenting concurrent work. They can be processed by Grand Central Dispatch. They can be executed by NSOperationQueue.

But even more importantly, they can capture state. Now, if you're going to have some concurrent work happening, it's great to be able to encapsulate that work, throw it out there, and have that block capture all the state it needs so it doesn't rely on you staying around anymore.

So, from that point of view, blocks are also good hit for concurrent work, but note that not all block usage is necessarily concurrent, and we'll see examples of this later. Now, in our-- in the APIs we're adding, when we want to enable concurrency, there's often an explicit option, for instance, enumeration, sorting, searching. Here's an NSArray method enumerateObjectsWithOptions:usingBlock. Here's a usage case for it. If you provide the option NSEnumerationConcurrent, the block is executed concurrently with elements in that array, so that's an explicit way to get concurrency out of enumeration.

If you're at the What's New In Foundation talk, Tuesday, you probably saw this in a lot of the other related APIs that we introduced in iOS 4 and Snow Leopard. Here's another example, NSNotifications. Observers can now indicate that they want to receive notifications concurrently. For that, we have a new method, addObserverForName object queue usingBlock. If the observer indicates a non-nil queue, the block will be executed concurrently for that observer. So, this is again, an explicit way to indicate your find for concurrency. And here's one more example out of the spell, NSSpellChecker class.

NSSpellChecker can do the spell checking. This class does the spell checking, grammar checking, et cetera. It can do the checking either in a synchronous fashion with this method where this method simply returns the result as its return value, which makes sense for a synchronous approach, and then returns additional results here in these two argument, or it can do it asynchronously with this method where the results are communicated in the completion handler block at a later time, and the results are returned in these arguments, passed to the block.

And also note one more thing, the sequence number passed to the block is actually the integer value that was returned by this method so that you can associate the request and the reply at a later time when the reply comes in. OK. So, with that, we get to our safety section. And here, I'm going to talk about runtime errors, programming errors, and also atomicity. So, safety is important because, you know, you can reduce the chance of crashes with safer programming.

You can make debugger, debugging more easy, and also writing more robust apps, which even if errors occur, it can indicate to the user why errors occur then allow the user to recover is a good idea. Now, there are two types of errors that we're going to talk about, expected errors which we also call runtime errors and programming errors which are sort of these unexpected errors that are caused by often bugs in the program.

Now runtime errors are errors that are expected to occur. For instance unreadable file, a file gets corrupt, the user tries to open it, they get an error -- out of disc space, user is trying to save a file but the disk was full, lost network connection, invalid user input, you're trying to make a trade and you indicate billions instead of millions you know it might happen. So these are the kind of errors that your program should guard against. Now these are typically handled with return values in an optional NSerror.

The return value is often a boolean or an object that returns an initialized object or nil. And in cases where you want to report an error you would use NSError argument, here's an example. Here the ID returns, you know, returns in your object, if it returns nil then the error argument, NSError** that's a by reference argument indicates what the error is. And of course as before you can pass NULL here if you don't want to hear about that error.

Now sometimes NSErrors can be passed by other means for instance here is a UIWebView delegate method, if an error occurs during loading, this delegate method is called and the error is simply passed to the delegate. And here's another example: NSWorkspace. This is a method to NSWorkspace to make copies of files just like the finder does on the desktop.

This is an asynchronous call in a way to you pass the URLs to copy and the completion handler is called with the NSDictionary indicating to you what the new names of the copied files are and in addition NSError which could be nil if no error occurred or maybe an error that indicates a partial error like 3 of the files could not be copied but the rest were. So this is actually a pretty novel way of using and indicating a partial error.

Now not all APIs need NSError in fact if you look at our APIs you probably see only a few percent of them have NSErrors. That's because NSError usage is really best confined to API's you know where you really want the caller to either look at the error and make decision based on the error type.

But even that's a chore you know having to look through the NSError, figure out the code, have a big switch statement and then in the future new codes are added you know that's not fun. So the other, the more compelling reason to add NSError is that the error may be reported to the user.

What I mean by that is you get an error from an API. You know, you can just put it up to the user and in fact have the error automatically provide ways of recovery from that error and NSError has that. It has the failure reason which is localized and it's got recovery suggestion and even a way to provide recovery options. And the errors we provide out of our frameworks usually have well localized error messages and sometimes recovery suggestions as well.

And if you're using the App Kit there's this responder API that will let you present an error either modally or as a sheet. But on UIKit as well you can actually take an NSError and show the various localized pieces in whatever fashion you want. OK. So let's talk about programming errors. And these are errors often caused by misuse of APIs. Here's an example.

This is out of bounds access into an array. Here's another example where you're calling a method which expects a caller but you're calling it with a string, you know sort of maybe looks like a caller. And an invalid parameter value, we often consider nil not to be a valid string when passed to APIs and you know this is a bad call here setStringValue of nil. Now we do not indicate programming errors by return values because programming errors are really errors in programming in program logic and these should be fixed and dealt with before you ship the application. It's not something that you'd expect to deal with on the user's machine at runtime.

You want to deal with it before you ship so you, you know, you test, you find these bugs, you fix them. So there's no need to deal with them at runtime. So therefore you will never see an API like this, setBackgroundColor, which returns an error code. And if you happen to pass in a string instead, it will return an error indicating a string passed in. I mean how do you deal with the set runtime is just like why would you do that, you just fix this bug. In fact, the compiler will probably tell you that you're passing a wrong argument if you have a type checking happening.

So, not a good idea. We indicate these errors via exceptions using NSException and it's important to note that in this fashion, Cocoa uses exceptions in somewhat different ways than some other frameworks than some other platforms do, so that is the difference in the way exceptions are used on our system.

And you know, we do not expect you to handle exceptions. For instance, you shouldn't have to write code where you set a background color and then put that tri-cache block around it just in case a string was passed and so you can cache it or run deal with it. Again. don't write this kind of code.

Just listen to the compiler and try to fix these bugs-- discover and fix this bug before you ship your application. Now, it might still be a good idea to have a top-level exception handling in your application. So if these kinds of exceptions do occur for the user, you know, you should be aware, hopefully.

You can alert the user something bad happened or you can try to recover and let them say-- now, if you write the Cocoa chips-- Tips and Tricks Talk on Tuesday at 2 p.m., you saw a technique a way of doing this on the-- in the context AppKit. So, the last safety topic I want to talk about is atomicity.

Objective-C 2.0 properties are by default atomic but they can be made non-atomic by putting non-atomic keywords. And many APIs in iOS, in iPhone OS are actually have non-atomic properties. Now, here's what atomic does. It guarantees that when one thread is setting or another-- and another thread is getting a value, you're guaranteed to get a good value.

And the good value is either the previous value or the next value, but you're guaranteed not to get some corrupt value that will make you crash or some half-set value, for instance a rectangle whose origin comes from some place and size comes from some place else. So that's what atomic guarantee is. It's not very much.

So it gives you a basic low-level of thread safety for single property but it can actually prevent crashes in the presence of threading in your application. So it's a good idea. Now, it's important to note, this does not provide consistency between properties. It does not give you high level of thread safety.

For instance, let's say you have one part of your program setting the first name and last name on an object, on a person object and some other part of your program reading the first name and last name. If this guy sets the first name while-- and then this guy comes in and then fetches the first name and last name, it will get back an invalid name. That's what I mean by how to look consistency. You know, it might get back a name like Bill Jobs or Steve Gates, you know, that would be good. An abomination. [Laughter] So you want to-- you know, that's that high-level consistency I'm taking about.

Now, atomicity is still often a good idea to use. Leave properties atomic. It is safer. When you might concern an atomic is, if you notice when you do use instruments for instance, if you know this calls to objc_getProperty or setProperty keep appearing in your back traces and taking some CPU time. That's when you might want to concern using anatomic. Another case you might want to drop atomic is if you already have higher level synchronization.

You know, I just mentioned an example of where you might use higher level synchronization. So if you already have locks or if you're already using cues or if you already have single-threaded access to your objects, you know, as long as those objects are confined to those contexts, you might want to non-atomic properties. The Cocoa Performance Techniques talk, from two years ago, if you can find the video in our developer's site, has some more about this topic.

OK. So with that, I want to move to the next major section which is Reusability. And by Reusability, I also mean Extensibility. In this section, we'll talk about subclassing categories on patterns for communicating changes. So why is Reusability important? Well, clearly, there's no need reinvent the wheel over and over. If you can reuse something that somebody else did, that's good.

And from our point of view, we want to give you API's that allow you to do what every application does, so that you can go ahead write the code on top of it that distinguishes your application. So we want you to be able to reuse our code as much as possible so you can do the creative things that make your application shine. And also, you, yourself, can write code which can be reused elsewhere. Maybe you can write some objects in this application and then use them in another project you're doing by writing reusable code.

So subclassing is the fundamental object-oriented programming feature, of course, for your Reusability. You know, we all know about it. But it's not very commonly used in Cocoa and Cocoa Touch for customization. Most of our classes are concrete, meaning they're usable as is and they're fairly customizable. So often, rather than using subclassing to customize objects, you just set various properties to make them behave in different ways. However, we do have some classes which are meant for subclassing. Sometimes, they're abstract, meaning you have to subclass them. And other times, they're semi-abstract, meaning their functional as is, but they probably want to be subclassed.

Examples are NSObject, UIView, et cetera, NSDocument. These are classes that often subclassed. In these cases you want to identify which methods are there for overwriting. NSObject init for instance, if you don't have a custom initialization. If you don't have custom drawing in your UI view, drawRect, and so on.

But then there's this other subtle scenario that we have in our frameworks, and I wanted to talk about that now. Some foundation classes such as NSString, NSData, et cetera, are absesetract, but they're also fully usable, which means you can alloc init these and you will get back a fully functional instance. You know, you've done this many times in your code, I'm sure.

However, if you try to subclass these, you find that subclasses do not work unless you've gone ahead and implemented a few methods, overridden a few methods, and these are Primitive-- what we call Primitive methods. Primitive methods are the minimal API to implement a new subclass. In the case of NSString, there is just two methods. Just by overriding these two methods in your subclass of NSString, you have a fully functional NSString that does everything any NSString can do.

So why do we have this approach? Why are these classes abstract? Well, for one reason. We have a bunch private implementation classes that are hidden behind a facade, like NSString, an abstract class, and we don't want to expose those private classes. So we have this behavior where subclassing is actually giving you the abstract class. But another important reason is that we do not want to encourage subclassing these classes for the wrong reason, and the wrong reason being to add additional properties.

And that's because it changes fundamental meaning of this object, what this object stores. And let me explain that to you. Here's NSString, it's got two fundamental methods, length and characterAtIndex. This is how an NSString is defined. Let's say you subclass NSString with a RichString because you-- RichString is just like a string. It's got length, characterAtIndex, but it also has a font.

Now, let's try to use these two classes in a program. You create a string, its value is hello. You create a RichString, its value is hello, but it also has the font, Helvetica. Now you ask the string, is it equal to the RichString? So the string says, "Hey, my contests are hello.

That other strings contents are hello." because it only knows how to look at the character values, and it says, "Yeah, sure. We're equal." Of course, if you ask the RichString, "Are you equal to this poor string, the RichString puts on a monocle, takes a look and says, "No, that string is not Helvetica.

We're not equal." So suddenly, you're violating some law, law of physics or math, I don't know, but you have A is equal to B--

But B is not equal to A, and that's just a very bad thing in programming. So therefore, this is a bad idea. Let's take a look at NSString versus NSAttributedSring and how we designed those just to solve this problem. So NSString has length and characterAtIndex.

We have this other class NSAttributedString, I already mentioned. It has a string and it has attributesAtIndex to represent the attributes. So rather than NSAttributedString being a subclass of NSString, it has a string. And both of these are subclasses of NSObject, and that solves this problem I'm talking about. So this is a good design here.

OK. So then, the question is, why would you subclass NSString, NSData, et cetera, if you know, we're making it hard to subclass? Well, there're still reasons to subclass it, and the biggest one is that you want to provide your own implementation. For instance, you could override the Primitives and have your own storage your data, for instance, goes to a file lazily.

You know, I often get the question, how can you make NSString read a four gigabyte file and efficiently? Well, you know, you could subclass it to do that, or various other ways of approaching large data storage. You can have NSString with a tree backing storage if you want.

Just by overriding those two methods, you get that behaviors. The Class Clusters documentation from the Cocoa Fundamentals Guide goes into more details on this Class Cluster approach. So we were talking about subclassing so far, and that's one way we can extend our classes. But another way we extend our classes is via Categories. Categories is a language feature, and it allows adding methods on existing classes where all instances are affected. This enables several things.

One of them is that you can actually distribute your methods across multiple header files, which is nice. But the other more interesting behavior is that you can extend a class without subclassing, so that all instances of that class are affected. For instance, NSString isn't Foundation. Foundation knows nothing about drawing, so NSString cannot draw. However, both UIKit and AppKit add new functionality, add joint functionality to NSString. For instance, UIKit adds methods, drawInRect withFont, drawAtPoint withFont.

So let me show you how this works. Let's say we have a drawable string subclass. So here's NSString, its got length, characterAtIndex, and bunch of other methods. We go ahead and give you a drawable string subclass which knows how to drink-- how-- not to drink. How to--

How to draw.

OK. And then if you create, if you have other subclasses, some subclass and another subclass, you can see that these subclasses do not know how to draw, so to draw a string you'd have to take these other instances and convert them to drawable strings before they can draw. So this sort of violates that all impedance matching thing, you know, where you have to convert types just to make them draw.

So, this is not a very good design, but by using categories, you have NSString, the category is added into the string at runtime so some of the NSString knows how to draw. It replies to drawInRect, drawAtPoint, et cetera. And then your subclasses are now magically also able to draw although, you know they have nothing to do it because these methods are part of the super implementation. So that's what categories enable.

Now, in addition to subclassing and categories, one other way to, of course-- another way to extend behaviors of classes is to have helper classes, helper objects. And so, we have several patterns for communicating changes. You're probably familiar with these: delegation, notification, key-value observing, target-action. If not, we do have some good documentation on this in the Cocoa Design Patterns documentation in the Cocoa Fundamentals Guide. But let me just go over how these are used to extend behaviors.

Delegation allows an object to act on behalf of another. It's not a language feature unlike categories. Classes explicitly support delegates. UITextView for instance declares that it has a delegate as you can see here with this @property and the delegate responds to a protocol and this protocol lists the methods that the delegate is expected to implement.

In this case, they're all optional so delegate might choose to implement only some of them. For instance, textViewShouldBeginEditing, et cetera. Now, delegation allows an object to help another object. It even allows one object to help many other objects. For instance, you might have one text view and you might have a delegate. You might have another text view and it might share the same delegate.

In fact, you might have a table view and it also might share the same delegate. If you do this, of course, that delegate should respond to the UITableView delegate protocol as well. As you can see I just added, they are in that bubble. Now, delegates are also flexible.

There are other object that are also sort of like delegates, for instance UITableView also has a data source and that could be another object, even a distinct object then its delegate. So delegation allows proper subdivision of responsibility and it's fairly flexible. You can make it flexible. So delegation, you know, if I were to give you an analogy, a delegate is like almost your doctor or your lawyer or maybe your spouse. You know somebody who you trust in and somebody who makes some of the decisions for you or maybe gives you some advice on how to do things, so that's sort of an appropriate analogy for delegation.

You know, for instance, if you have an NSWindow and the NSWindow is being closed, decision whether that window should be closed or not, it's not really the window's place to decide. It's really the place of whoever has content being displayed in that window to decide whether it's OK to close that.

So that's why the window asks its delegate should the window close. Notification is another pattern. Notification allows-- I was going to use the word "event" here but "event" is so overloaded I said "happenings," which is an interesting word. It allows happenings to be broadcast to a set of unrelated observers. These observers observe but they don't interfere.

This is unlike delegation where the delegates do have the ability to interfere. This also is in a language feature. There is a class NSNotification center and classes have to explicitly declare notifications they post. For instance, we have many notifications both in UIKit and AppKit, UIPasteboardChangedNotification, NSWindowWillCloseNotification and so on. Now, note that sometimes delegate methods, you know they might also be delegate methods that correspond to this and so the delegate might also act as an observer in some cases.

Now notifications is pretty flexible. You know you can have multiple observers. There is an indirection between the objects so that observers can actually choose to observe any notification from a particular object or a notification from any object. That's because, you know, here are the objects we have. Here are observers. There is intermediate notification center. All the notifications are posted there and the notification center sends the notifications to appropriate interested objects.

So, if I were to give an analogy here, this is almost like, you know, somebody whose twittering or I know you're doing it now, but it's almost like twittering or blogging. Let's say your blogging away telling the world about interesting things that happen to you. That might turn out nobody is reading your blog or maybe some people signed up for your RSS feeds.

So those are the observers, and you actually don't even know how many observers you have. You know, they are just independently signing up for your blog and you're just telling the world of what you think is important, so that's like notifications. You choose to tell the world what's important and they choose to listen if they want to.

Key-value observing is another pattern, I'll just quickly go over this one. This one allows objects to broadcast updates to individual properties. You know, like a window can say, my title changed. An employee can say, my salary changed, and so on. This also is on a language feature. Classes decide which properties they want to implement this for.

However, unlike delegation notification, this doesn't require defining any new APIs, any new symbols, and any new protocols. You know, a class just says, hey, you know, my salary property is observable. In fact, if those properties are key-value coding compliant, which is pretty much automatic if you use that property for instance, the key-value observing is also automatically available in most cases.

Now, key-value observing is most appropriate when you have UIElements showing various properties. For instance, you have a text field showing the salary. That text field is interested in hearing a lot of changes to that salary field and, you know, not necessarily any other notifications coming from that object, so you would use key-value observing for cases like that.

And finally, target action, this is a fairly specialized simple approach. It allows UIControl syndicate user interaction. It's simple and it works well in Interface Builder. You know, control simply sends a customizable action to a customizable target. This becomes more flexible when you have your target specified as nil because then the responder chain is used to find the appropriate target at runtime. That's why for instance when you hit command C, an application to copy, the appropriate, whatever the current text field is active, gets to command C.

We don't have to specify that target ahead of time and continuously change it. The responder chain is a fairly powerful concept that you can also use for your own purposes if you need to. For instance, we use a responder chain also in error presentation. We just throw the error down the responder chain in the appropriate window, and if there's no window, maybe the application will be shown there. The one final thing I'm going to talk about in this section is Model View Controller and this is a huge topic.

In fact, I talked about it earlier. I just want to have one slide. Model-View-Controller is a pattern that defines three clear functional roles for objects, the model which owns the data, view which displays and lets the user edit the data, and the controller which coordinates things. Each piece is separately replaceable, customizable, and that's why this pattern is so powerful. You can choose to replace the model or the view.

For instance if you're going to write a cross platform app that works well on the iPad, the iPhone, and the Mac, you would use the ModelViewController paradigm to split your pieces so you can reuse your model, for instance. This is used for overall app design, but also various subsystems through our APIs use this pattern.

The Cocoa text system, the bindings architecture, UITableView, so individual classes even like UITableView, NSTableView, UIViewController use this pattern. So two talks during the week touched upon this pattern, the model-view controller talk and Advanced Cocoa Text Tips & Tricks talks both showed examples of how we use MVC in our APIs.

OK, so with that, now we're in the convenience section, we're going to talk about convenience APIs and blocks. So, why is convenience important? Well, there are three reasons. One is that it allows you to be more productive. Convenience APIs allow you to do more with even less code.

It also makes coding fun, you know, effortless. You know, it seems more easy to do things. Now, the third reason is that I found out when I was looking at a definition of convenience, I don't know why I did that. Apparently convenience means public toilet in British English.

And that's important.

And let me use it in a sentence. At the bash tonight, you will probably need a convenience if you drink too much beer. Anyway, so with that-- so, convenience APIs are APIs that simplify or combine a number of other calls into one. For instance, here's an NSString method that does comparisons and it's got four arguments. We have a convenience method on it, compare: that just has one argument and basically fills in the other three arguments.

Now, we clearly don't have convenience APIs everywhere we could. You know, otherwise, sometimes, you look for a convenience API and you don't see it and you have to call a bigger method and you're like, I wish there was a convenience API. You know if you had convenience APIs everywhere possible, that'd be a lot of APIs, so we usually consider these APIs only in cases where the implementation is more than two lines or there are some additional value in the convenience or there's some valuable abstraction in the convenience, and let me explain what I mean by those last two.

Here are the two methods I showed you earlier. Here's the way the compare method, the single argument one is implemented. It simply calls the four argument method with a bunch of default arguments. I mean, if you look at it, it's really a one line implementation, right? I mean I graphed it so it looks good, but it's really one line.

You know, you're thinking why is there a convenience method here? Well, that's because there is additional value in this method. The compare method allows you-- allows-- you know it can be used in sorting methods. For instance, NSArray has sort using selector. It takes a selector with one argument. So, you can just pass the compare method right in there.

In fact, we have more NSString comparison conveniences such as case insensitive compare, localized compare and so on just for this purpose. So the-- there's additional value in these methods, in these conveniences. Another reason is valuable abstraction. Here's a method we recently added in Snow Leopard and iOS 4. This does a comparison just like the system does and we described that this method's behavior may change over time.

Here's the implementation we tell you. This is-- if you look in the release nodes, this is the exact implementation today. However, as I said, we may change this implementation over time. So here, this method is valuable because of its abstraction that the implementation may change, so it's more than in fact the convenience in this case. By using it, you will get this abstraction of comparing just like the system does.

OK, so the next topic here is blocks. Now, when you think about it, blocks are mostly for convenience. Blocks do not really enable anything that was impossible before. You know, they bring a lot of convenience. You can specify a piece of code in line. You don't have to create an extra function, and they have this ability to capture state, which you can also emulate. Now, I don't want to sell blocks short. Blocks are an amazing feature. In fact they are so amazing we added them to the language. In fact, we added them to C, you know, for which the bar is pretty high, so they are an amazing feature.

But in the end, they really bring a lot of convenience. For instance, we use blocks as callbacks and we're replacing the places where they appear as callbacks. In fact, all those compare variants are really not that necessary anymore. For instance before, if you did not have a compare method you might have wanted like a numeric search, you would have had to go and define your own custom function and then pass it to myArray, you know, NSArray sort using function. While before with blocks, you can just do sortUsingComparator and pass the block right in there and the code you want to do is right in there, so this is pretty convenient. You don't need all those compare variants anymore.

Another thing we use blocks for is completions, for instance new APIs for presenting sheets in AppKit and in the same panel. Here's what the Leopard API looks like and here's what the Snow Leopard API looks like. It's considerably simpler. Note that we replace these last three arguments to delegate the selector and the context in full with just the block.

Also note that one thing we've done here is get rid of this pesky void star argument. Refining that, void star arguments are really more trouble than they're worth and we're looking at getting rid of them from our APIs as much as possible, and for one thing they really do not behave very well under GC for instance.

Here, one final example of blocks as conveniences, the new APIs we've added in UIView, for instance animateWithDuration animation looks fairly convenient. In fact, it replaces three lines of boilerplate code like here, that this is the code you would have had to use on iPhone OS 3 with just one line where you're specifying the animations you want right there in the body of the block, so again, super convenient.

Hopefully, here you've heard about how good API is very important part of Cocoa and Cocoa Touch design. We take a good API design very seriously and I hope I've been able to communicate how we do that and how you can also do it yourself in your own applications and in your own designs.

Now modeling your APIs as ours will allow your APIs to be more predictable so you can actually know almost all the new method names, just roll off your tongue, you don't have to worry about them. Widely reusable, you can use it in other projects, give it to other people, and they will also be better performing as you hopefully saw.

And one final warning, you know, API design is an evolving art. We have examples of some APIs that are not perfectly named. So, if you ever run across something that looks a bit fishy, maybe it is. So don't take, you know, everything strictly, but again most of our APIs are going in the right direction. For more information, you know, you can contact our evangelist and we have lot of great documentation, just the starting point, developer.apple.com. You can do searches for the various keywords I gave you, and there is a lot of great background stuff on this.