objective-c-style-guide-master.zip

# [DEPRECATED] NYTimes Objective-C Style Guide is deprecated. No more development will be taking place. Thanks for all your support! # NYTimes Objective-C Style Guide This style guide outlines the coding conventions of the iOS teams at The New York Times. We welcome your feedback in [issues](https://github.com/NYTimes/objective-c-style-guide/issues) and [pull requests](https://github.com/NYTimes/objective-c-style-guide/pulls). Also, [we’re hiring](http://www.nytco.com/careers/). Thanks to all of [our contributors](https://github.com/NYTimes/objective-c-style-guide/graphs/contributors). ## Introduction Here are some of the documents from Apple that informed the style guide. If something isn’t mentioned here, it’s probably covered in great detail in one of these: * [The Objective-C Programming Language](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html) * [Cocoa Fundamentals Guide](https://developer.apple.com/legacy/library/documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html) * [Coding Guidelines for Cocoa](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html) * [iOS App Programming Guide](http://developer.apple.com/library/ios/#documentation/iphone/conceptual/iphoneosprogrammingguide/Introduction/Introduction.html) This style guide conforms to IETF's [RFC 2119](http://tools.ietf.org/html/rfc2119). In particular, code which goes against the RECOMMENDED/SHOULD style is allowed, but should be carefully considered. ## Table of Contents * [Dot Notation Syntax](#dot-notation-syntax) * [Spacing](#spacing) * [Conditionals](#conditionals) * [Ternary Operator](#ternary-operator) * [Error handling](#error-handling) * [Methods](#methods) * [Variables](#variables) * [Naming](#naming) * [Categories](#categories) * [Comments](#comments) * [Init & Dealloc](#init-and-dealloc) * [Literals](#literals) * [CGRect Functions](#cgrect-functions) * [Constants](#constants) * [Enumerated Types](#enumerated-types) * [Bitmasks](#bitmasks) * [Private Properties](#private-properties) * [Image Naming](#image-naming) * [Booleans](#booleans) * [Singletons](#singletons) * [Imports](#imports) * [Protocols](#protocols) * [Xcode Project](#xcode-project) ## Dot Notation Syntax Dot notation is RECOMMENDED over bracket notation for getting and setting properties. **For example:** ```objc view.backgroundColor = UIColor.orangeColor; UIApplication.sharedApplication.delegate; ``` **Not:** ```objc [view setBackgroundColor:[UIColor orangeColor]]; [UIApplication sharedApplication].delegate; ``` ## Spacing * Indentation MUST use 4 spaces. Never indent with tabs. Be sure to set this preference in Xcode. * Method braces and other braces (`if`/`else`/`switch`/`while` etc.) MUST open on the same line as the statement. Braces MUST close on a new line. **For example:** ```objc if (user.isHappy) { // Do something } else { // Do something else } ``` * There SHOULD be exactly one blank line between methods to aid in visual clarity and organization. * Whitespace within methods MAY separate functionality, though this inclination often indicates an opportunity to split the method into several, smaller methods. In methods with long or verbose names, a single line of whitespace MAY be used to provide visual separation before the method’s body. * `@synthesize` and `@dynamic` MUST each be declared on new lines in the implementation. ## Conditionals Conditional bodies MUST use braces even when a conditional body could be written without braces (e.g., it is one line only) to prevent [errors](https://github.com/NYTimes/objective-c-style-guide/issues/26#issuecomment-22074256). These errors include adding a second line and expecting it to be part of the if-statement. Another, [even more dangerous defect](http://programmers.stackexchange.com/a/16530) can happen where the line “inside” the if-statement is commented out, and the next line unwittingly becomes part of the if-statement. In addition, this style is more consistent with all other conditionals, and therefore more easily scannable. **For example:** ```objc if (!error) { return success; } ``` **Not:** ```objc if (!error) return success; ``` or ```objc if (!error) return success; ``` ### Ternary Operator The intent of the ternary operator, `?` , is to increase clarity or code neatness. The ternary SHOULD only evaluate a single condition per expression. Evaluating multiple conditions is usually more understandable as an if statement or refactored into named variables. **For example:** ```objc result = a > b ? x : y; ``` **Not:** ```objc result = a > b ? x = c > d ? c : d : y; ``` ## Error Handling When methods return an error parameter by reference, code MUST switch on the returned value and MUST NOT switch on the error variable. **For example:** ```objc NSError *error; if (![self trySomethingWithError:&error]) { // Handle Error } ``` **Not:** ```objc NSError *error; [self trySomethingWithError:&error]; if (error) { // Handle Error } ``` Some of Apple’s APIs write garbage values to the error parameter (if non-NULL) in successful cases, so switching on the error can cause false negatives (and subsequently crash). ## Methods * In method signatures, there SHOULD be a space after the scope (`-` or `+` symbol). There SHOULD be a space between the method segments. **For example:** ```objc - (void)setExampleText:(NSString *)text image:(UIImage *)image; ``` * Methods exceeding 80 characters SHOULD be represented like a form with a new line after each argument **For example:** ```objc - (void)setExampleText:(NSString *)text image:(UIImage *)image color:(UIColor *)color alternativeText:(NSString *)altText; ``` ## Variables Variables SHOULD be named descriptively, with the variable’s name clearly communicating what the variable _is_ and pertinent information a programmer needs to use that value properly. **For example:** * `NSString *title`: It is reasonable to assume a “title” is a string. * `NSString *titleHTML`: This indicates a title that may contain HTML which needs parsing for display. _“HTML” is needed for a programmer to use this variable effectively._ * `NSAttributedString *titleAttributedString`: A title, already formatted for display. _`AttributedString` hints that this value is not just a vanilla title, and adding it could be a reasonable choice depending on context._ * `NSDate *now`: _No further clarification is needed._ * `NSDate *lastModifiedDate`: Simply `lastModified` can be ambiguous; depending on context, one could reasonably assume it is one of a few different types. * `NSURL *URL` vs. `NSString *URLString`: In situations when a value can reasonably be represented by different classes, it is often useful to disambiguate in the variable’s name. * `NSString *releaseDateString`: Another example where a value could be represented by another class, and the name can help disambiguate. Single letter variable names are NOT RECOMMENDED, except as simple counter variables in loops. Asterisks indicating a type is a pointer MUST be “attached to” the variable name. **For example,** `NSString *text` **not** `NSString* text` or `NSString * text`, except in the case of constants (`NSString * const NYTConstantString`). Property definitions SHOULD be used in place of naked instance variables whenever possible. Direct instance variable access SHOULD be avoided except in initializer methods (`init`, `initWithCoder:`, etc…), `dealloc` methods and within custom setters and getters. For more information, see [Apple’s docs on using accessor methods in initializer methods and `dealloc`](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmPractical.html#//apple_ref/doc/uid/TP40004447-SW6). **For example:** ```objc @interface NY