After WWDC, there are new SDKs (Software Development Kits), APIs (Application Programming Interfaces) and new languages to play around with, along with the usual extensions to existing interfaces. Getting up to speed quickly with a new SDK, especially a pre-release SDK, can mean the difference between having a good time with new software toys or becoming angry and making those around you miserable.
It’s OK to be frustrated
New APIs can be baffling. Things may be designed in ways that are obvious to the original developer but not for the world at large. Sometimes class nomenclature may be from the point of view of the implementor vs the programmer using it. The original
NSOperation API included “concurrent” and “non-concurrent” operations. Unfortunately, the names were backwards to those of us creating our own operations: non-concurrent operations were the ones that actually ran concurrently on multiple threads, and concurrent operations didn’t. Thankfully Apple has dropped that distinction.
Brand new APIs may be incomplete, lacking features that are obvious in retrospect. There are also just plain old bugs. These are pre-release versions of operating systems, after all.
No matter whether your opinion of the Apple bug reporting process is good or bad, now is definitely the time to “file radars” via http://bugreport.apple.com. It’s in everybody’s best interest that API deficiencies get fixed before they’re permanently baked into an official OS release.
It’s also better to get bugs reported earlier rather than later. Building an operating system or two is an extremely complex task. If you wait too long, you may find that the SDK you discovered a new bug or API oddity in might already be locked down, with engineering resources already allocated elsewhere. So if you see a new API that you think will be important to you in the near future, concentrate on it as soon as possible.
Breaking Down the Complexity
There’s a new SDK that interests you. How do you approach it and make the best use of your time? I approach it in three phases:
- Learn the lingo
- Figure out the actors
- Learn the interactions
Learn the Lingo
Every SDK has its set of terms and concepts—its own physics, if you will. These fundamental concepts shape the objects that are involved and how they work together. The session videos are the best starting out places. Complex SDKs, or those that are kind of weird, might warrant a couple of watchings. The videos, even if somewhat dry, give you the vision of the SDK, what it’s trying to accomplish, and some of the main paths through its features.
I like building a glossary of terms as I watch. I can refer back to that glossary while learning the API to figure out what Apple means by certain words. For example,
AVFoundation has vocabulary like Assets, Composition, Metadata and Track that are important to know.
Figure out the Actors
Apple tends to have a small number of API patterns it uses, which you’ve probably seen in the Mac OS X or iOS APIs you use. These patterns appear again and again in new SDKs. Notifications. Delegation. Queues. Blocks.
Look for any “context” objects, things like
UIDynamicAnimator. These are central objects that vend out other objects, or exert some kind of control over your use of the tools. These live in the center of activity for the library, and are good to learn.
Skim the documentation to see the responsibilities these context objects have. How are they created? Do you create a new context and use it? Maybe you have to get them from class methods. Are they singletons (ugh) or can you have many? Perhaps there are shared versions for convenience, but you can create your own if needed like with
Is the SDK inheritance or composition based? Do you derive new objects from existing ones and override methods to provide behavior, or do you take an object and just use it? iOS 7 transitions are a composite-flavor API, while
UIDocument is a subclassing-flavor API. Typically, compositional APIs are simpler to deal with: “Here is a set of tools you can use,” while a subclassing API requires you to know the class’s entire state machine.
Many APIs require construction of an object graph, such as
UIKitDynamics using behaviors, items and animators.
UICollectionView has cell and layout objects. You’ll need to have a rough idea of what each individual class is responsible for and how they interact. It can be really frustrating to wonder why your code isn’t working. Then you realize that you forgot to create some vitally important object. Sometimes connection order is important.
Look to see if there are delegates involved, and what the responsibilities of those delegates are. Maybe the API is notification based. Some newer API is queue-and-block based. Take a look around for the kinds of work that get performed on the queues. In general, be paranoid about whether a block callback or a notification happens on a background thread before touching any UI classes.
Taking a Header
The documentation for many new SDKs that appears at WWDC can be pretty minimal. The session video usually has the best introductory material. The highest profile SDKs usually have the best supporting information. For everything else, it can be sketchy. As good as Apple’s techpubs crew is, there’s a finite number of them, and they have pretty hard deadlines for WWDC releases.
The header files are next stop for infoseeking—they often have the best documentation for new technologies, and for technologies that are not on the most-popular path. Apple has limited resources for documenting stuff, so the developer comments in the headers might be the only real explanation of what’s going on.
If you’re learning a new-to-you SDK that’s been around for awhile, you can see how the API has evolved by looking at the availability Macros. You’ll also know not to waste time with calls that were deprecated in iOS 7 when you’re targeting iOS 13.
One little trick when scanning the enums that describe various options and knobs for a library: If they look like bit flags (like
1 << 23), you’ll most likely be able to combine them. If they’re sequential integers, you’ll most likely be using them independently.
The headers may be terse, and sometimes they’re forward-looking (that is, they describe the end goal of the API, not what actually is available today). Sample code, if it’s available, frequently becomes the de-facto documentation.
Coding against new APIs is my favorite part. I’ve surveyed the land to figure out the moving pieces, and perhaps I’ve run Apple’s sample code to see how things work. Now it’s time to make my own thing.
For an iOS SDK, I’ll make a new Xcode project and throw a tab bar controller into it. Each tab will exercise different aspects of the API. “Hello world” goes into one view controller, a reproduction of Apple’s sample code goes into another. Code that exhaustively tests all the delegate methods might go into a third. This lets you have one app to exercise the SDK (and exchange between friends and coworkers), but you don’t have to have one gigantic bolus of code with everything shoehorned into it.
Implement all the delegate methods and subscribe to all of the notifications. Put in log statements that dump out the data passed to them (especially notification user info dictionaries). It helps describe the flow of data and control through the toolkit, and will also force you to familiarize yourself with all of the customization hooks.
I would not recommend immediately integrating an SDK into your mainline codebase while you’re learning it. Write small experimental demos first so you learn the pros and cons of the SDK before disturbing your production code. The time to integrate an SDK into your main program is after you understand the SDK.
Don’t Be Afraid To Hack
This is the perfect time to unleash all your exploration and debugging skills. Got a baffling problem? Apply the Universal Troubleshooting Process or remember that Everything You Know Is Wrong. Feel free to use your Leveling Up skills and attack the problem with disassemblers, class-dump, and DTrace.
New SDKs can be fun, especially when Apple takes something that has traditionally been pretty hard and makes it simple to use. They can also be frustrating. Please file bugs early and often especially for pre-release toolkits. Life is so much easier if bugs and API deficiencies are addressed before they’re baked into an OS release. Use exploratory coding to figure out what’s going on before integrating the new SDK into your main application. And don’t forget that frustration is part of the job (and part of the fun, if you’re weird) when dealing with new APIs.