Up until a week or so ago, I’d not touched Cocoa. I’d delved into Objective C a little, and played with Foundation, but that was it.
The single hardest part of it for me to deal with was the lack of solid example snippets attached to references. Apple just doesn’t document its frameworks that way, and this is probably a contributory factor in the sheer number of Cocoa books out there. What Apple tends to do is give you a reference to a class, with a short sentence or two on each method, and links to some example code which makes some use of the class (and you’ve got to employ educated guesswork to figure out how or why it uses that class, which doesn’t help when you want a quick three-line snippet demonstrating the use of a particular method).
A good example is NSTimer. I (probably wrongly, in all honesty), use NSTimer in DropLook’s preferences controller so as to keep the “Last updated” label current—from my reading of Sparkle’s documentation, it was a choice between periodically checking [[SUUpdater] sharedUpdater] updateInProgress] and [[SUUpdater] sharedUpdater] lastUpdateCheckDate], or altering Sparkle’s code to send more fine-grained messages to its delegate when the state changes. Because I’d already spent more time integrating Sparkle than I had writing DropLook’s core functionality, I opted for the former.
Using NSTimer is straightforward, provided you already know how to use NSTimer. I didn’t. There are two ways of creating an unscheduled timer: timerWithTimeInterval:invocation:repeats: and timerWithTimeInterval:target:selector:userInfo:repeats:. The former is listed first in the documentation and has a simpler method signature, so I opted for that… foolishly. It would have been much simpler to use the latter. At this point, I’d been writing Cocoa for about 3 hours in total, and so I didn’t know if getting an NSInvocation was the preferred way of specifying a timer callback or not. Perhaps it’s just the way my brain works, but I could’ve read an example for timerWithTimeInterval:invocation:repeats: and would have immediately seen using this method would be making life difficult for myself when all I want to do is invoke [self timerTick] every so often.
It’s certainly true that you pick this stuff up over time—a seasoned Cocoa developer wouldn’t get unstuck at the choice between NSInvocation and a target/selector pair, but that initial learning curve strikes me as being a little steeper than it could be.
In the (g)olden days, when I programmed in Object Pascal, Borland’s online help was exemplary: pretty much all of the methods were well-documented, and each had an attached example program demonstrating their use. Sometimes a few methods would share an example, but the program was never more than about 30 lines of code—very easy for a programmer to digest without losing focus on the task at hand.
One answer is to rely on the books, but that poses its own problems: you have to have read the books first, and they have to be up to date (none of the Cocoa books I have currently deal with Xcode 3, which is fine for a lot of things, but gets confusing when it comes to Interface Builder tutorials).
So, Apple… short examples along with method references? Please?