Marco.org

One of the surprisingly useful sessions from WWDC 2010 was #138: API Design for Cocoa and Cocoa Touch.

The title wasn’t a very good expression of its content. It’s more fairly (albeit verbosely) titled, “Conventions, naming styles, and structural guidelines that Apple has used for the Cocoa APIs, and how and why you should adopt them.”

Some tips included, from my notes:

• Name all of the arguments to reduce readers’ trips to the documentation. Consider removeObjectAtIndex:: You know exactly what the parameter should be.
• Don’t abbreviate unless it’s a very common abbreviation.
  • Good: PDF, URL, Max, Min.
  • Bad: Str, Fmt, Dat.
• Don’t prefix method names with “do”, “compute”, etc.
• Getters shouldn’t be prefixed with “get”, with two exceptions:
  • Use “get” on accessors that return values by reference, e.g. NSData’s getBytes.
  • Prefix BOOL getters with “is”, e.g. isEditable. Shortcut: @property (getter=isEditable) BOOL editable;
• Avoid names with ambiguous meanings or parts of speech, e.g.: displayName, center.

• Exceptions in Cocoa are meant to indicate programming errors, not expected operating conditions. (Like assertions.)

  Exceptions are typically not meant to be caught. They’re not supposed to ever fire in a shipping app.

Apple’s developers have made their style and API design decisions with far more time, wisdom, and experience than any individual developer is likely to have. There will always be exceptions to conventions in real-world use, but when you can more fully appreciate why those conventions are in place, you can more responsibly choose when to break from them.

This was one of the sessions that has had the most lasting value for me,¹ but I attended it by chance: there was nothing else pertinent to me during that hour, so I ducked into this one, thinking it was about entirely different matter. I’m glad I did.

If you’re a registered iPhone developer, get it: go here (you’ll need to log in), follow one of those iTunes links, select the “Application Frameworks” category, and download Session 138.