[UPDATE: See the comments for some great ways to find sample code. I retract my "Dark Ages" characterization. I'd still like to see that boilerplate stripped out though…]

There's a variety of options today — options that continue to improve — for finding stuff in the Cocoa documentation. We're still in the Dark Ages, however, when it comes to finding sample code.

Finding stuff in the docs

In a post entitled "Helping people", Peter Hosey discusses recurring themes he's encountered when helping newcomers to Cocoa and Cocoa Touch. One recurring theme is the ability to find stuff out for oneself:

Somewhere on Eric Raymond's site, there's an explanation of the difference between newbies and wizards. It's not that the wizards know all that much more than the newbies (though they often do have a stronger/deeper conceptual understanding); asked for the name of a function, say, the wizard will probably not know it exactly (unless it is very simple, such as CFRetain, or one they use very frequently, such as CFRetain).

The difference between them is that the wizard knows where to look stuff up.

I think any introductory book on Cocoa programming should include a chapter or at least a sidebar on "looking stuff up." It's an essential part of the skill of developing in Cocoa, and for me a big part of the pleasure. The consistent naming, the recurring design patterns, and the well written docs are all good things brought over from NextStep.

I wrote AppKiDo in the early days of Cocoa to scratch my own itch around looking stuff up. The Xcode doc browser has gotten very powerful over the years, so these days I use it a lot as well, along with Command-Option-doubleclick. Try searching for "programming guide" in the Xcode docs and see all the goodies that turn up. The "programming guides" are what used to be the "conceptual docs" in NextStep.

Occasionally I use Google (usually with site:developer.apple.com as a search term) and StackOverflow.

There are other approaches and ideas for searching and exploring the docs, including:

• "Xcode UI Improvements", an essay by Brandon Walkin.
• Ingredients, a very smart and modern doc browser that Brandon likes a lot.
• Cocoa Browser Air, which I notice uses SAX parsing on the docs. I should look into using this approach myself; I'll look at the source when I get a chance.
• This clever use of OmniWeb, which I just noticed was posted by Peter Hosey.

Finding stuff in sample code

Besides documentation, another kind of "stuff" that's invaluable to programmers is sample code.

Some sample code is provided by third parties, either specifically for that purpose (for example, mmalc, NSBlog, CocoaDev, and CodeBeach) or as a side benefit of being open source. Ad hoc sample code is often exchanged on mailing lists like cocoa-dev, sometimes with the disclaimer that it's been typed off the cuff and not been compiled, much less tested.

Apple provides code for hundreds of complete sample projects, with convenient links to the examples sprinkled all throughout the documentation, and a search page both in Xcode and online (here for Cocoa and here for iOS). This is all great, but I wish the tools for finding sample code, and the code itself, received the kind of care and attention that the docs do.

Here are my main gripes about Apple sample code.

• Search is not useful. On the sample code search page, enter "sample code nstask". Nothing comes up, when at the very least Moriarity should.
  • Suggestions for Apple:
    • Search the projects' README files.
    • Search for projects that use a given class or protocol.
    • Search for method names, both in methods implemented and messages sent. If someone on cocoa-dev says "look at performSelector:withObject:afterDelay:", a quick search should turn up example projects that use that method. Note that this requires Objective-C files to be indexed in a special way; grep-like search doesn't work with multi-part method names.
• Examples sometimes don't build. The reason is always because they're out of date. Would you believe — Moriarity still comes with a .pbproj, meaning I can't even convert it to a .xcodeproj without a Leopard machine running Xcode 2.5. I've run into example projects that target 10.4 and complain that this is incompatible with GCC 4.2. Easy to work around, but an inconvenience. I've also seen other compile errors.
  • Suggestions for Apple:
    • Set up an automated regression testing procedure that checks the example code for build errors in a variety of environments.
    • Put someone in charge of cleaning up projects that "break the build".
    • Put example code into a publicly readable version control repository so we can see what changes have been made and why.
• Examples sometimes don't set the best example. In fairness, I say "sometimes" but I only know of one example — Moriarity. It should really use naming conventions from the delegate pattern for what it calls the controller. If there are other examples I'd like to know about them.
  • Suggestions for Apple:
    • Ideally someone at Apple would decide it's worth a programmer's time to rework the code. I don't think this is likely to happen.
    • Alternatively, Apple could accept (or link to) submissions from third parties that are revisions of their sample code. Also unlikely, I'm afraid.
• Copyright boilerplate is annoying. It's a real turnoff, over and over, to open a source file and see no source code but instead a window full of boilerplate legalese about how we're free to use the code as long as we do this and that. I would go so far as to call this a usability flaw, because it makes me scroll down every time to get to the useful part of the file, and this is distracting. Imagine if the New York Times put a page full of boilerplate at the top of every article.
  • Suggestions for Apple:
    • Move the boilerplate to a separate file, like License.txt. Please.

If only…

It would be nice if there were an easy way to download all of Apple's sample projects. Apple could bundle them similarly to how it bundles documentation — perhaps in "codesets" rather than docsets, complete with an RSS feed like there is for the documentation. Then third parties could provide solutions for searching, regression testing, revision tracking, and boilerplate-stripping.

This would be nice, but I doubt Apple would invest the effort. Alternatively, I could simply download all the examples myself with a little web scraping, and get updates by checking the site now and then. If I ever catch up on the stuff in my queue now, maybe I'll find time to do that.