Looking stuff up: docs and sample code

[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.

9 thoughts on “Looking stuff up: docs and sample code

  1. Great post.

    The one bit I’d disagree with is that sample code is invaluable.

    Sample code is invaluable when the documentation sucks. If I want to learn how an API works, I’d much rather have a good conceptual explanation than a sample application I have to poke through. Delegate methods are one good example of something sample code doesn’t illustrate well.

    The only thing I’ve found Apple’s samples useful for is cribbing code, when they’ve already written something that I need. Even then, it’s worth giving the function a good looking-over, since it may very well not be up to my coding standards. (For example, more than once have I seen a suppressed error return.)

    At that point, it’s less sample code—serving to demonstrate an API—and more reusable source code with a demo app around it.

    Whatever time Apple spends writing a sample app, I’d say would be better spent either writing some of its functions/methods as part of the API (a lot of the functions in the MoreWhatever samples provoke the question of why they aren’t just part of the API) or writing/improving the documentation for the API.

    Then again, you’re not the first person I’ve heard praise for sample code from, so am I just weird like that?

  2. I think there’s a lot to be said for cribbing code!

    I think it’s a case of different strokes for different folks, and of course using docs and sample code aren’t mutually exclusive. Historically I haven’t relied a lot on sample code until recently when I was looking at some third party libraries, and when I took a quick look at iOS.

    Suppose I want to study a new API, even for just one class. Sometimes I create my own little “etude” app, but sometimes it’s convenient to have one ready-made that I can pick apart. There’s something about having a working app as an existence proof that I find helpful, if only psychologically. And people who cannot seem to get something to work, despite doing everything “right,” can compare their code to working sample code.

    When I finally get around to real iOS coding (one of these days, I swear), I look forward to messing with the examples I saw listed — my quick impression is that they will be very useful. I think I learn a little from the exercise of trying to find fault with them too, so part of me actually doesn’t mind them not being perfect. I do wish they were more discoverable though.

  3. Hi Andy,

    These are great suggestions.

    Apple would do well to “make them so”!

    Thanks, joely

  4. Finding sample code has gotten a lot better in recent Xcode releases. Sample projects are now listed next to many APIs and the full text results for an API often return source files. For example, search for “performSelector:withObject:afterDelay:” in Xcode 3.2. Under the full text section there are source files from several sample projects listed.

  5. I’d like to add my extension to the list of tools for searching documentation.

    I got tired of sifting through Google’s ever-decreasing relevant results when searching for API info, so I wrote a Safari & Firefox extension to search the Apple Developer Central website only.

    You can download it here: http://acmeinc.org/extensions

    shameless plug

  6. Matt,

    True.

    Sal,

    Thanks. I installed the extension and it works as advertised. I get tired of typing site:developer.apple.com myself.

    Ron,

    Nice work. Search is snappy, the page is pleasant to look at, and the controls for refining the result set are nice. Sorting by Type makes it easy to spot the sample code links. Sorting in descending alphabetical order makes it even easier, since it often puts “Sample Code” at the top; hits in the “Technical Notes”, “Technical Q&As”, and “Video” categories are relatively few.

    It does seem odd that searching for “sample code nstask” across the entire Developer Library (using the search field at the top) gets much better results than searching for “nstask” within the Sample Code category (using the “Documents ### of 3122″ search field).

  7. Apple Developer Forums become a place where you can get real help beyond the docs. Similarly, Apple would consider to make an official Git repository for their sample code.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>