Introducing the raywenderlich.com Objective-C Style Guide

One of the goals of this web site is to continuously improve the way we make our tutorials and books. One of the things we want to improve upon in the coming year is improving our consistency across tutorials and books by different authors.

To aid with this goal, the team and I are very pleased to announce the official raywenderlich.com Objective-C style guide!

This style guide is different than other style guides out there, in that its focus is on readability for printed books and the web. Many of the decisions were made with an eye toward conserving space for print, easy legibility, and tutorial writing.

So without further ado, check out the style guide or keep reading for the highlights of the guide, who worked on it, and what the most controversial bits were!

How Was This Guide Developed?

This style guide was developed as a group effort from across the team.

I (Nicholas Waynik) served as the project manager for the style guide. I put together the initial draft and posted it to Github for review. If a team member wanted to change something they simply submitted a pull request. I’d then go through and accept, comment, or reject any pull requests. Github Issues were used for changes requiring debate or group input. Once the team collectively agreed upon a change it was then made.

The style guide team members included: Soheil Moayedi Azarpour, Ricardo Rendon Cepeda, Tony Dahbura, Colin Eberhardt, Matt Galloway, Greg Heo, Matthijs Hollemans, Christopher LaPollo, Saul Mora, Andy Pereira, Mic Pringle, Pietro Rea, Cesare Rocchi, Marin Todorov, Nicholas Waynik, and Ray Wenderlich.

Guide Highlights and Controversies

There are some parts of the style guide that we agreed upon without a hitch:

• Naming and Methods. Naming variables and methods well substantially aids readability and understanding, well worth the cost of printed space.
• Constants and Enums. We recommend using static variables and the new NS_ENUM keyword.
• Dot Notation and Literals. We’re a big fan of dot notation and literal syntax on raywenderlich.com for enhanced conciseness and readability.
• The Smiley Face. There is only one true smiley face :]

However, there were some parts where the discussions got quite heated! If you’ve ever had a discussion with fellow programmers on the proper placement of a curly brace, I’m sure you know what I mean :]

The part of the guide that was the most controversial by far was the answer to this question: Should you prefer private instance variables, or private properties?

• Main argument for preferring private instance variables: Do the simplest possible thing that works (and prefer saving space). Why add the overhead/complexity of private properties if you don’t need them?
• Main argument for preferring private properties: Properties bring a lot of Objective-C goodness such as key-value coding, future proofness, a little more consistent overall.

Both approaches are completely valid ways of doing things, and both sides had valid points. However, we felt we should choose one for consistency’s sake.

After a heated 118-comment discussion, StackOverflow discussion, and very close vote, private properties won the day – at least for now :]

How We’ll Use This Guide

We will strongly recommend tutorial authors on our site use this style guide moving forward. However, note that not every tutorial will be 100% compliant to the style guide – it’s asking a bit much for authors and editors to do that for free tutorials.

However, we will enforce and authors and editors use the style guide in future books and starter kits we develop on this site – as we always aim for a higher bar with those.

Comments on the Guide?

As we learned from developing this guide, there are always going to be strong opinions on code style issues.

And we’d love to hear yours! Do you love/hate any decisions we’ve made in the style guide? Post comments on this thread or file GitHub pull requests – I’ll be watching for them, and if you can convince me (and the rest of the team), we’ll change the guide.

We hope you enjoy our Objective-C style guide – and stay tuned for some more consistent tutorials and books! :]