readability-cli 0.4.0__py3-none-any.whl

guides/objcguide.md

@@ -0,0 +1,2386 @@
+# Google Objective-C Style Guide
+
+> Objective-C is a dynamic, object-oriented extension of C. It's designed to be
+> easy to use and read, while enabling sophisticated object-oriented design. It
+> is one of the primary development languages for applications on Apple
+> platforms.
+>
+> Apple has already written a very good, and widely accepted, [Cocoa Coding
+> Guidelines](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html)
+> for Objective-C. Please read it in addition to this guide.
+>
+> The purpose of this document is to describe the Objective-C (and
+> Objective-C++) coding guidelines and practices. These guidelines have evolved
+> and been proven over time on other projects and teams.
+> Open-source projects developed by Google conform to the requirements in this guide.
+>
+> Note that this guide is not an Objective-C tutorial. We assume that the reader
+> is familiar with the language. If you are new to Objective-C or need a
+> refresher, please read [Programming with
+> Objective-C](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html).
+
+
+
+## Principles
+
+### Optimize for the reader, not the writer
+
+Codebases often have extended lifetimes and more time is spent reading the code
+than writing it. We explicitly choose to optimize for the experience of our
+average software engineer reading, maintaining, and debugging code in our
+codebase rather than the ease of writing said code. For example, when something
+surprising or unusual is happening in a snippet of code, leaving textual hints
+for the reader is valuable.
+
+### Be consistent
+
+When the style guide allows multiple options it is preferable to pick one option
+over mixed usage of multiple options. Using one style consistently throughout a
+codebase lets engineers focus on other (more important) issues. Consistency also
+enables better automation because consistent code allows more efficient
+development and operation of tools that format or refactor code. In many cases,
+rules that are attributed to "Be Consistent" boil down to "Just pick one and
+stop worrying about it"; the potential value of allowing flexibility on these
+points is outweighed by the cost of having people argue over them.
+
+### Be consistent with Apple SDKs
+
+Consistency with the way Apple SDKs use Objective-C has value for the same
+reasons as consistency within our code base. If an Objective-C feature solves a
+problem that's an argument for using it. However, sometimes language features
+and idioms are flawed, or were just designed with assumptions that are not
+universal. In those cases it is appropriate to constrain or ban language
+features or idioms.
+
+### Style rules should pull their weight
+
+The benefit of a style rule must be large enough to justify asking engineers to
+remember it. The benefit is measured relative to the codebase we would get
+without the rule, so a rule against a very harmful practice may still have a
+small benefit if people are unlikely to do it anyway. This principle mostly
+explains the rules we don’t have, rather than the rules we do: for example, goto
+contravenes many of the following principles, but is not discussed due to its
+extreme rarity.
+
+<a id="Example"></a>
+
+## Example
+
+They say an example is worth a thousand words, so let's start off with an
+example that should give you a feel for the style, spacing, naming, and so on.
+
+Here is an example header file, demonstrating the correct commenting and spacing
+for an `@interface` declaration.
+
+```objectivec
+// GOOD:
+
+#import <Foundation/Foundation.h>
+
+@class Bar;
+
+/**
+ * A sample class demonstrating good Objective-C style. All interfaces,
+ * categories, and protocols (read: all non-trivial top-level declarations
+ * in a header) MUST be commented. Comments must also be adjacent to the
+ * object they're documenting.
+ */
+@interface Foo : NSObject
+
+/** The retained Bar. */
+@property(nonatomic) Bar *bar;
+
+/** The current drawing attributes. */
+@property(nonatomic, copy) NSDictionary<NSString *, NSNumber *> *attributes;
+
+/**
+ * Convenience creation method.
+ * See -initWithBar: for details about @c bar.
+ *
+ * @param bar The string for fooing.
+ * @return An instance of Foo.
+ */
++ (instancetype)fooWithBar:(Bar *)bar;
+
+/**
+ * Initializes and returns a Foo object using the provided Bar instance.
+ *
+ * @param bar A string that represents a thing that does a thing.
+ */
+- (instancetype)initWithBar:(Bar *)bar NS_DESIGNATED_INITIALIZER;
+
+/**
+ * Does some work with @c blah.
+ *
+ * @param blah
+ * @return YES if the work was completed; NO otherwise.
+ */
+- (BOOL)doWorkWithBlah:(NSString *)blah;
+
+@end
+```
+
+An example source file, demonstrating the correct commenting and spacing for the
+`@implementation` of an interface.
+
+```objectivec
+// GOOD:
+
+#import "Shared/Util/Foo.h"
+
+@implementation Foo {
+  /** The string used for displaying "hi". */
+  NSString *_string;
+}
+
++ (instancetype)fooWithBar:(Bar *)bar {
+  return [[self alloc] initWithBar:bar];
+}
+
+- (instancetype)init {
+  // Classes with a custom designated initializer should always override
+  // the superclass's designated initializer.
+  return [self initWithBar:nil];
+}
+
+- (instancetype)initWithBar:(Bar *)bar {
+  self = [super init];
+  if (self) {
+    _bar = [bar copy];
+    _string = [[NSString alloc] initWithFormat:@"hi %d", 3];
+    _attributes = @{
+      @"color" : UIColor.blueColor,
+      @"hidden" : @NO
+    };
+  }
+  return self;
+}
+
+- (BOOL)doWorkWithBlah:(NSString *)blah {
+  // Work should be done here.
+  return NO;
+}
+
+@end
+```
+
+<a id="Naming"></a>
+
+## Naming
+
+Names should be as descriptive as possible, within reason. Follow standard
+[Objective-C naming
+rules](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html).
+
+Avoid non-standard abbreviations (including non-standard acronyms and
+initialisms). Don't worry about saving horizontal space as it is far more
+important to make your code immediately understandable by a new reader. For
+example:
+
+```objectivec
+// GOOD:
+
+// Good names.
+int numberOfErrors = 0;
+int completedConnectionsCount = 0;
+tickets = [[NSMutableArray alloc] init];
+userInfo = [someObject object];
+port = [network port];
+NSDate *gAppLaunchDate;
+```
+
+```objectivec
+// AVOID:
+
+// Names to avoid.
+int w;
+int nerr;
+int nCompConns;
+tix = [[NSMutableArray alloc] init];
+obj = [someObject object];
+p = [network port];
+```
+
+Any class, category, method, function, or variable name should use all capitals
+for acronyms and [initialisms](https://en.wikipedia.org/wiki/Initialism) within
+(including at the beginning of) the name. This follows Apple's standard of using
+all capitals within a name for acronyms such as URL, ID, TIFF, and EXIF.
+
+Names of C functions and typedefs should be capitalized and use camel case as
+appropriate for the surrounding code.
+
+<a id="Inclusive_Language"></a>
+
+### Inclusive Language
+
+In all code, including naming and comments, use inclusive language and avoid
+terms that other programmers might find disrespectful or offensive (such as
+"master" and "slave", "blacklist" and "whitelist", or "redline"), even if the
+terms also have an ostensibly neutral meaning. Similarly, use gender-neutral
+language unless you're referring to a specific person (and using their
+pronouns). For example, use "they"/"them"/"their" for people of unspecified
+gender (even when singular), and "it"/"its" for non-people.
+
+
+<a id="File_Names"></a>
+
+### File Names
+
+File names should reflect the name of the class implementation that they
+contain—including case.
+
+Follow the convention that your project uses.
+
+File extensions should be as follows:
+
+Extension | Type
+--------- | ---------------------------------
+.h        | C/C++/Objective-C header file
+.m        | Objective-C implementation file
+.mm       | Objective-C++ implementation file
+.cc       | Pure C++ implementation file
+.c        | C implementation file
+
+Files containing code that may be shared across projects or used in a large
+project should have a clearly unique name, typically including the project or
+class [prefix](#prefixes).
+
+File names for categories should include the name of the class being extended,
+like GTMNSString+Utils.h or NSTextView+GTMAutocomplete.h
+
+### Prefixes
+
+Prefixes are commonly required in Objective-C to avoid naming collisions in a
+global namespace. Classes, protocols, global functions, and global constants
+should generally be named with a prefix that begins with a capital letter
+followed by one or more capital letters or numbers.
+
+WARNING: Apple reserves two-letter prefixes—see
+[Conventions in Programming with Objective-C](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html)—so
+prefixes with a minimum of three characters are considered best practice.
+
+```objectivec
+// GOOD:
+
+/** An example error domain. */
+GTM_EXTERN NSString *GTMExampleErrorDomain;
+
+/** Gets the default time zone. */
+GTM_EXTERN NSTimeZone *GTMGetDefaultTimeZone(void);
+
+/** An example delegate. */
+@protocol GTMExampleDelegate <NSObject>
+@end
+
+/** An example class. */
+@interface GTMExample : NSObject
+@end
+
+```
+
+<a id="Class_Names"></a>
+
+### Class Names
+
+Class names (along with category and protocol names) should start as uppercase
+and use mixed case to delimit words.
+
+Classes and protocols in code shared across multiple applications must have an
+appropriate [prefix](#prefixes) (e.g. GTMSendMessage). Prefixes are recommended,
+but not required, for other classes and protocols.
+
+<a id="Category_Names"></a>
+
+### Category Naming
+
+Category names should start with an appropriate [prefix](#prefixes) identifying
+the category as part of a project or open for general use.
+
+Category source file names should begin with the class being extended followed
+by a plus sign and the name of the category, e.g., `NSString+GTMParsing.h`.
+Methods in a category should be prefixed with a lowercase version of the prefix
+used for the category name followed by an underscore (e.g.,
+`gtm_myCategoryMethodOnAString:`) in order to prevent collisions in
+Objective-C's global namespace.
+
+There should be a single space between the class name and the opening
+parenthesis of the category.
+
+```objectivec
+// GOOD:
+
+// UIViewController+GTMCrashReporting.h
+
+/** A category that adds metadata to include in crash reports to UIViewController. */
+@interface UIViewController (GTMCrashReporting)
+
+/** A unique identifier to represent the view controller in crash reports. */
+@property(nonatomic, setter=gtm_setUniqueIdentifier:) int gtm_uniqueIdentifier;
+
+/** Returns an encoded representation of the view controller's current state. */
+- (nullable NSData *)gtm_encodedState;
+
+@end
+```
+
+If a class is not shared with other projects, categories extending it may omit
+name prefixes and method name prefixes.
+
+```objectivec
+// GOOD:
+
+/** This category extends a class that is not shared with other projects. */
+@interface XYZDataObject (Storage)
+- (NSString *)storageIdentifier;
+@end
+```
+
+<a id="Objective-C_Method_Names"></a>
+
+### Objective-C Method Names
+
+Method and parameter names typically start as lowercase and then use mixed case.
+
+Proper capitalization should be respected, including at the beginning of names.
+
+```objectivec
+// GOOD:
+
++ (NSURL *)URLWithString:(NSString *)URLString;
+```
+
+The method name should read like a sentence if possible, meaning you should
+choose parameter names that flow with the method name. Objective-C method names
+tend to be very long, but this has the benefit that a block of code can almost
+read like prose, thus rendering many implementation comments unnecessary.
+
+Use prepositions and conjunctions like "with", "from", and "to" in the second
+and later parameter names only where necessary to clarify the meaning or
+behavior of the method.
+
+```objectivec
+// GOOD:
+
+- (void)addTarget:(id)target action:(SEL)action;                          // GOOD; no conjunction needed
+- (CGPoint)convertPoint:(CGPoint)point fromView:(UIView *)view;           // GOOD; conjunction clarifies parameter
+- (void)replaceCharactersInRange:(NSRange)aRange
+            withAttributedString:(NSAttributedString *)attributedString;  // GOOD.
+```
+
+If the method returns an attribute of the receiver, name the method after the
+attribute.
+
+```objectivec
+// GOOD:
+
+/** Returns this instance's sandwich. */
+- (Sandwich *)sandwich;      // GOOD.
+
+- (CGFloat)height;           // GOOD.
+
+// GOOD; Returned value is not an attribute.
+- (UIBackgroundTaskIdentifier)beginBackgroundTask;
+```
+
+```objectivec
+// AVOID:
+
+- (CGFloat)calculateHeight;  // AVOID.
+- (id)theDelegate;           // AVOID.
+```
+
+An accessor method should be named the same as the object it's getting, but it
+should not be prefixed with the word `get`. For example:
+
+```objectivec
+// GOOD:
+
+- (id)delegate;     // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+- (id)getDelegate;  // AVOID.
+```
+
+Accessors that return the value of boolean adjectives have method names
+beginning with `is`, but property names for those methods omit the `is`.
+
+Dot notation is used only with property names, not with method names.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, getter=isGlorious) BOOL glorious;
+// The method for the getter of the property above is:
+// - (BOOL)isGlorious;
+
+BOOL isGood = object.glorious;      // GOOD.
+BOOL isGood = [object isGlorious];  // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+BOOL isGood = object.isGlorious;    // AVOID.
+```
+
+```objectivec
+// GOOD:
+
+NSArray<Frog *> *frogs = [NSArray<Frog *> arrayWithObject:frog];
+NSEnumerator *enumerator = [frogs reverseObjectEnumerator];  // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+NSEnumerator *enumerator = frogs.reverseObjectEnumerator;    // AVOID.
+```
+
+See [Apple's Guide to Naming
+Methods](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-BCIGIJJF)
+for more details on Objective-C naming.
+
+These guidelines are for Objective-C methods only. C++ method names continue to
+follow the rules set in the C++ style guide.
+
+<a id="Function_Names"></a>
+
+### Function Names
+
+Function names should start with a capital letter and have a capital letter for
+each new word (a.k.a. "[camel case](https://en.wikipedia.org/wiki/Camel_case)"
+or "Pascal case").
+
+```objectivec
+// GOOD:
+
+static void AddTableEntry(NSString *tableEntry);
+static BOOL DeleteFile(const char *filename);
+```
+
+Because Objective-C does not provide namespacing, non-static functions should
+have a [prefix](#prefixes) that minimizes the chance of a name collision.
+
+```objectivec
+// GOOD:
+
+GTM_EXTERN NSTimeZone *GTMGetDefaultTimeZone(void);
+GTM_EXTERN NSString *GTMGetURLScheme(NSURL *URL);
+```
+
+<a id="Variable_Names"></a>
+
+### Variable Names
+
+Variable names typically start with a lowercase and use mixed case to delimit
+words.
+
+Instance variables have leading underscores. File scope or global variables have
+a prefix `g`. For example: `myLocalVariable`, `_myInstanceVariable`,
+`gMyGlobalVariable`.
+
+<a id="Common_Variable_Names"></a>
+
+#### Common Variable Names
+
+Readers should be able to infer the variable type from the name, but do not use
+Hungarian notation for syntactic attributes, such as the static type of a
+variable (int or pointer).
+
+File scope or global variables (as opposed to constants) declared outside the
+scope of a method or function should be rare, and should have the prefix `g`.
+
+```objectivec
+// GOOD:
+
+static int gGlobalCounter;
+```
+
+<a id="Instance_Variables"></a>
+
+#### Instance Variables
+
+Instance variable names are mixed case and should be prefixed with an
+underscore, like `_usernameTextField`.
+
+NOTE: Google's previous convention for Objective-C ivars was a trailing
+underscore. Existing projects may opt to continue using trailing underscores in
+new code in order to maintain consistency within the project codebase.
+Consistency of prefix or suffix underscores should be maintained within each
+class.
+
+<a id="Constants"></a>
+
+#### Constants
+
+Constant symbols (const global and static variables and constants created
+with #define) should use mixed case to delimit words.
+
+Global and file scope constants should have an appropriate [prefix](#prefixes).
+
+```objectivec
+// GOOD:
+
+/** The domain for GTL service errors. */
+GTL_EXTERN NSString *const GTLServiceErrorDomain;
+
+/** An enumeration of GTL service error codes. */
+typedef NS_ENUM(int32_t, GTLServiceError) {
+  /** An error code indicating that a query result was missing. */
+  GTLServiceErrorQueryResultMissing = -3000,
+  /** An error code indicating that the query timed out. */
+  GTLServiceErrorQueryTimedOut      = -3001,
+};
+```
+
+Because Objective-C does not provide namespacing, constants with external
+linkage should have a prefix that minimizes the chance of a name collision,
+typically like `ClassNameConstantName` or `ClassNameEnumName`.
+
+For interoperability with Swift code, enumerated values should have names that
+extend the typedef name:
+
+```objectivec
+// GOOD:
+
+/** An enumeration of supported display tinges. */
+typedef NS_ENUM(int32_t, DisplayTinge) {
+  DisplayTingeGreen = 1,
+  DisplayTingeBlue = 2,
+};
+```
+
+A lowercase k can be used as a standalone prefix for constants of static storage
+duration declared within implementation files:
+
+```objectivec
+// GOOD:
+
+static const int kFileCount = 12;
+static NSString *const kUserKey = @"kUserKey";
+```
+
+NOTE: Previous convention was for public constant names to begin with a
+lowercase k followed by a project-specific [prefix](#prefixes). This practice is
+no longer recommended.
+
+<a id="Types_and_Declarations"></a>
+
+## Types and Declarations
+
+<a id="Method_Declarations"></a>
+
+### Method Declarations
+
+As shown in the [example](#Example), the recommended order
+for declarations in an `@interface` declaration are: properties, class methods,
+initializers, and then finally instance methods. The class methods section
+should begin with any convenience constructors.
+
+<a id="Local_Variables"></a>
+
+### Local Variables
+
+Declare variables in the narrowest practical scopes, and close to their use.
+Initialize variables in their declarations.
+
+```objectivec
+// GOOD:
+
+CLLocation *location = [self lastKnownLocation];
+for (int meters = 1; meters < 10; meters++) {
+  reportFrogsWithinRadius(location, meters);
+}
+```
+
+Occasionally, efficiency will make it more appropriate to declare a variable
+outside the scope of its use. This example declares meters separate from
+initialization, and needlessly sends the lastKnownLocation message each time
+through the loop:
+
+```objectivec
+// AVOID:
+
+int meters;                                         // AVOID.
+for (meters = 1; meters < 10; meters++) {
+  CLLocation *location = [self lastKnownLocation];  // AVOID.
+  reportFrogsWithinRadius(location, meters);
+}
+```
+
+Under Automatic Reference Counting, strong and weak pointers to Objective-C
+objects are automatically initialized to `nil`, so explicit initialization to
+`nil` is not required for those common cases. However, automatic initialization
+does *not* occur for many Objective-C pointer types, including object pointers
+declared with the `__unsafe_unretained` ownership qualifier and CoreFoundation
+object pointer types. When in doubt, prefer to initialize all Objective-C
+local variables.
+
+### Static Variables
+
+When file scope variable/constant declarations in an implementation file do not
+need to be referenced outside that file, declare them static (or in an anonymous
+namespace in Objective-C++). Do not declare file scope variables or constants
+with static storage duration (or in anonymous namespaces in Objective-C++) in .h
+files.
+
+```objectivec
+// GOOD:
+
+// file: Foo.m
+static const int FOORequestLimit = 5;
+```
+
+```objectivec
+// AVOID:
+
+// file: Foo.h
+static const int FOORequestLimit = 5;  // AVOID.
+```
+
+<a id="Unsigned_Integers"></a>
+
+### Unsigned Integers
+
+Avoid unsigned integers except when matching types used by system interfaces.
+
+Subtle errors crop up when doing math or counting down to zero using unsigned
+integers. Rely only on signed integers in math expressions except when matching
+NSUInteger in system interfaces.
+
+```objectivec
+// GOOD:
+
+NSUInteger numberOfObjects = array.count;
+for (NSInteger counter = numberOfObjects - 1; counter >= 0; --counter)
+```
+
+```objectivec
+// AVOID:
+
+for (NSUInteger counter = numberOfObjects - 1; counter >= 0; --counter)  // AVOID.
+```
+
+Unsigned integers may be used for flags and bitmasks, though often NS_OPTIONS or
+NS_ENUM will be more appropriate.
+
+<a id="Types_with_Inconsistent_Sizes"></a>
+
+### Types with Inconsistent Sizes
+
+Be aware that types long, NSInteger, NSUInteger and CGFloat have sizes that
+differ in 32- and 64-bit builds. Their use is appropriate when matching system
+interfaces but should be avoided when dealing with APIs that
+require exact sizing, e.g., proto APIs.
+
+```objectivec
+// GOOD:
+
+int32_t scalar1 = proto.intValue;
+
+int64_t scalar2 = proto.longValue;
+
+NSUInteger numberOfObjects = array.count;
+
+CGFloat offset = view.bounds.origin.x;
+```
+
+```objectivec
+// AVOID:
+
+NSInteger scalar2 = proto.longValue;  // AVOID.
+```
+
+File and buffer sizes often exceed 32-bit limits, so they should be declared
+using `int64_t`, not with `long`, `NSInteger`, or `NSUInteger`.
+
+<a id="Floating_Point_Constants"></a>
+
+#### Floating Point Constants
+
+When defining `CGFloat` constants, please keep in mind the following.
+
+Previously for projects targeting 32-bit platforms, using `float` literals
+(numbers with the `f` suffix) could be necessary to avoid type-conversion
+warnings.
+
+Since all Google iOS projects are now targeting only 64-bit runtime, `CGFloat`
+constants may omit the suffix (use `double` values). However, teams may choose
+to continue using `float` numbers for legacy code consistency, until they
+eventually migrate to `double` values everywhere. Avoid a mixture of `float`
+and `double` values in the same code.
+
+```objectivec
+// GOOD:
+
+// Good since CGFloat is double
+static const CGFloat kHorizontalMargin = 8.0;
+static const CGFloat kVerticalMargin = 12.0;
+
+// This is OK as long as all values for CGFloat constants in your project are float
+static const CGFloat kHorizontalMargin = 8.0f;
+static const CGFloat kVerticalMargin = 12.0f;
+```
+
+```objectivec
+// AVOID:
+
+// Avoid a mixture of float and double constants
+static const CGFloat kHorizontalMargin = 8.0f;
+static const CGFloat kVerticalMargin = 12.0;
+```
+
+<a id="Comments"></a>
+
+## Comments
+
+Comments are absolutely vital to keeping our code readable. The following rules
+describe what you should comment and where. But remember: while comments are
+important, the best code is self-documenting. Giving sensible names to types and
+variables is much better than using obscure names and then trying to explain
+them through comments.
+
+Pay attention to punctuation, spelling, and grammar; it is easier to read
+well-written comments than badly written ones.
+
+Comments should be as readable as narrative text, with proper capitalization and
+punctuation. In many cases, complete sentences are more readable than sentence
+fragments. Shorter comments, such as comments at the end of a line of code, can
+sometimes be less formal, but use a consistent style.
+
+When writing your comments, write for your audience: the next contributor who
+will need to understand your code. Be generous—the next one may be you!
+
+<a id="File_Comments"></a>
+
+### File Comments
+
+A file may optionally start with a description of its contents.
+
+Every file may contain the following items, in order
+  * License boilerplate if necessary. Choose the appropriate boilerplate for the
+    license used by the project.
+  * A basic description of the contents of the file if necessary.
+
+If you make significant changes to a file with an author line, consider deleting
+the author line since revision history already provides a more detailed and
+accurate record of authorship.
+
+
+<a id="Declaration_Comments"></a>
+
+### Declaration Comments
+
+Every non-trivial interface, public and private, should have an accompanying
+comment describing its purpose and how it fits into the larger picture.
+
+Comments should be used to document classes, properties, ivars, functions,
+categories, protocol declarations, and enums.
+
+
+```objectivec
+// GOOD:
+
+/**
+ * A delegate for NSApplication to handle notifications about app
+ * launch and shutdown. Owned by the main app controller.
+ */
+@interface MyAppDelegate : NSObject {
+  /**
+   * The background task in progress, if any. This is initialized
+   * to the value UIBackgroundTaskInvalid.
+   */
+  UIBackgroundTaskIdentifier _backgroundTaskID;
+}
+
+/** The factory that creates and manages fetchers for the app. */
+@property(nonatomic) GTMSessionFetcherService *fetcherService;
+
+@end
+```
+
+[Doxygen](https://doxygen.nl)-style comments are encouraged for interfaces as
+they are parsed by Xcode
+to display formatted documentation. There is a wide variety of
+[Doxygen commands](https://www.doxygen.nl/manual/commands.html);
+use them consistently within a project.
+
+If you have already described an interface in detail in the comments at the top
+of your file, feel free to simply state, "See comment at top of file for a
+complete description", but be sure to have some sort of comment.
+
+Additionally, each method should have a comment explaining its function,
+arguments, return value, thread or queue assumptions, and any side effects.
+Documentation comments should be in the header for public methods, or
+immediately preceding the method for non-trivial private methods.
+
+Use descriptive form ("Opens the file") rather than imperative form ("Open the
+file") for method and function comments. The comment describes the function; it
+does not tell the function what to do.
+
+Document the thread usage assumptions the class, properties, or methods make, if
+any. If an instance of the class can be accessed by multiple threads, take extra
+care to document the rules and invariants surrounding multithreaded use.
+
+Any sentinel values for properties and ivars, such as `NULL` or `-1`, should be
+documented in comments.
+
+Declaration comments explain how a method or function is used. Comments
+explaining how a method or function is implemented should be with the
+implementation rather than with the declaration.
+
+Declaration comments may be omitted on test case classes and test methods
+if comments would communicate no additional information beyond the method's
+name. Utility methods in tests or test-specific classes (such as helpers) should
+be commented.
+
+<a id="Implementation_Comments"></a>
+
+### Implementation Comments
+
+Provide comments explaining tricky, subtle, or complicated sections of code.
+
+```objectivec
+// GOOD:
+
+// Set the property to nil before invoking the completion handler to
+// avoid the risk of reentrancy leading to the callback being
+// invoked again.
+CompletionHandler handler = self.completionHandler;
+self.completionHandler = nil;
+handler();
+```
+
+When useful, also provide comments about implementation approaches that were
+considered or abandoned.
+
+End-of-line comments should be separated from the code by at least 2 spaces. If
+you have several comments on subsequent lines, it can often be more readable to
+line them up.
+
+```objectivec
+// GOOD:
+
+[self doSomethingWithALongName];  // Two spaces before the comment.
+[self doSomethingShort];          // More spacing to align the comment.
+```
+
+
+<a id="Disambiguating_Symbols"></a>
+
+### Disambiguating Symbols
+
+Where needed to avoid ambiguity, use backticks or vertical bars to quote
+variable names and symbols in comments in preference to using quotation marks
+or naming the symbols inline.
+
+In Doxygen-style comments, prefer demarcating symbols with a monospace text
+command, such as [`@c`](https://www.doxygen.nl/manual/commands.html#cmdc).
+
+Demarcation helps provide clarity when a symbol is a common word that might make
+the sentence read like it was poorly constructed. A common example is the symbol
+`count`:
+
+```objectivec
+// GOOD:
+
+// Sometimes `count` will be less than zero.
+```
+
+or when quoting something which already contains quotes
+
+```objectivec
+// GOOD:
+
+// Remember to call `StringWithoutSpaces("foo bar baz")`
+```
+
+Backticks or vertical bars are not needed when a symbol is self-apparent.
+
+```objectivec
+// GOOD:
+
+// This class serves as a delegate to GTMDepthCharge.
+```
+
+Doxygen formatting is also suitable for identifying symbols.
+
+```objectivec
+// GOOD:
+
+/** @param maximum The highest value for @c count. */
+```
+
+<a id="Object_Ownership"></a>
+
+### Object Ownership
+
+For objects not managed by ARC, make the pointer ownership model as explicit as
+possible when it falls outside the most common Objective-C usage idioms.
+
+<a id="Manual_Reference_Counting"></a>
+
+#### Manual Reference Counting
+
+Instance variables for NSObject-derived objects are presumed to be retained; if
+they are not retained, they should be either commented as weak or declared with
+the `__weak` lifetime qualifier.
+
+An exception is in Mac software for instance variables labeled as `@IBOutlets`,
+which are presumed to not be retained.
+
+Where instance variables are pointers to Core Foundation, C++, and other
+non-Objective-C objects, they should always be declared with strong and weak
+comments to indicate which pointers are and are not retained. Core Foundation
+and other non-Objective-C object pointers require explicit memory management,
+even when building for automatic reference counting.
+
+Examples of strong and weak declarations:
+
+```objectivec
+// GOOD:
+
+@interface MyDelegate : NSObject
+
+@property(nonatomic) NSString *doohickey;
+@property(nonatomic, weak) NSString *parent;
+
+@end
+
+
+@implementation MyDelegate {
+  IBOutlet NSButton *_okButton;  // Normal NSControl; implicitly weak on Mac only
+
+  AnObjcObject *_doohickey;  // My doohickey
+  __weak MyObjcParent *_parent;  // To send messages back (owns this instance)
+
+  // non-NSObject pointers...
+  CWackyCPPClass *_wacky;  // Strong, some cross-platform object
+  CFDictionaryRef *_dict;  // Strong
+}
+@end
+```
+
+<a id="Automatic_Reference_Counting"></a>
+
+#### Automatic Reference Counting
+
+Object ownership and lifetime are explicit when using ARC, so no additional
+comments are required for automatically retained objects.
+
+<a id="C_Language_Features"></a>
+
+## C Language Features
+
+<a id="Macros"></a>
+
+### Macros
+
+Avoid macros, especially where `const` variables, enums, Xcode snippets, or C
+functions may be used instead.
+
+Macros make the code you see different from the code the compiler sees. Modern C
+renders traditional uses of macros for constants and utility functions
+unnecessary. Macros should only be used when there is no other solution
+available.
+
+Where a macro is needed, use a unique name to avoid the risk of a symbol
+collision in the compilation unit. If practical, keep the scope limited by
+`#undefining` the macro after its use.
+
+Macro names should use `SHOUTY_SNAKE_CASE`—all uppercase letters with
+underscores between words. Function-like macros may use C function naming
+practices. Do not define macros that appear to be C or Objective-C keywords.
+
+```objectivec
+// GOOD:
+
+#define GTM_EXPERIMENTAL_BUILD ...      // GOOD
+
+// Assert unless X > Y
+#define GTM_ASSERT_GT(X, Y) ...         // GOOD, macro style.
+
+// Assert unless X > Y
+#define GTMAssertGreaterThan(X, Y) ...  // GOOD, function style.
+```
+
+```objectivec
+// AVOID:
+
+#define kIsExperimentalBuild ...        // AVOID
+
+#define unless(X) if(!(X))              // AVOID
+```
+
+Avoid macros that expand to unbalanced C or Objective-C constructs. Avoid macros
+that introduce scope, or may obscure the capturing of values in blocks.
+
+Avoid macros that generate class, property, or method definitions in
+headers to be used as public API. These only make the code hard to
+understand, and the language already has better ways of doing this.
+
+Avoid macros that generate method implementations, or that generate declarations
+of variables that are later used outside of the macro. Macros shouldn't make
+code hard to understand by hiding where and how a variable is declared.
+
+```objectivec
+// AVOID:
+
+#define ARRAY_ADDER(CLASS) \
+  -(void)add ## CLASS ## :(CLASS *)obj toArray:(NSMutableArray *)array
+
+ARRAY_ADDER(NSString) {
+  if (array.count > 5) {              // AVOID -- where is 'array' defined?
+    ...
+  }
+}
+```
+
+Examples of acceptable macro use include assertion and debug logging macros
+that are conditionally compiled based on build settings—often, these are
+not compiled into release builds.
+
+<a id="Nonstandard_Extensions"></a>
+
+### Nonstandard Extensions
+
+Nonstandard extensions to C/Objective-C may not be used unless otherwise
+specified.
+
+Compilers support various extensions that are not part of standard C. Examples
+include compound statement expressions (e.g. `foo = ({ int x; Bar(&x); x })`).
+
+#### The `__typeof__` Keyword
+
+The `__typeof__` keyword is allowed in cases where the type doesn't aid in
+clarity for the reader. The `__typeof__` keyword is encouraged over other
+similar keywords (e.g., the `typeof` keyword) as it is supported in all language
+variants.
+
+```objectivec
+// GOOD:
+
+  __weak __typeof__(self) weakSelf = self;
+```
+
+```objectivec
+// AVOID:
+
+  __typeof__(data) copiedData = [data copy];  // AVOID.
+  __weak typeof(self) weakSelf = self;        // AVOID.
+```
+
+#### The `__auto_type` Keyword and Type Deduction
+
+Type deduction using the `__auto_type` keyword is allowed only for local
+variables of block and function pointer types. Avoid type deduction if a typedef
+already exists for the block or pointer type.
+
+```objectivec
+// GOOD:
+
+__auto_type block = ^(NSString *arg1, int arg2) { ... };
+__auto_type functionPointer = &MyFunction;
+
+typedef void(^SignInCallback)(Identity *, NSError *);
+SignInCallback signInCallback = ^(Identity *identity, NSError *error) { ... };
+```
+
+```objectivec
+// AVOID:
+
+__auto_type button = [self createButtonForInfo:info];
+__auto_type viewController = [[MyCustomViewControllerClass alloc] initWith...];
+
+typedef void(^SignInCallback)(Identity *, NSError *);
+__auto_type signInCallback = ^(Identity *identity, NSError *error) { ... };
+```
+
+#### Approved Nonstandard Extensions
+
+*   The `__attribute__` keyword is approved as it is used in Apple API
+    declarations.
+*   The binary form of the conditional operator, `A ?: B`, is approved.
+
+<a id="Cocoa_and_Objective-C_Features"></a>
+
+## Cocoa and Objective-C Features
+
+<a id="Identify_Designated_Initializer"></a>
+
+### Identify Designated Initializers
+
+Clearly identify your designated initializer(s).
+
+It is important for subclassing that a class clearly identify its designated
+initializers. This allows a subclass to override a subset of initializers to
+initialize subclass state or invoke a new designated initializer provided by the
+subclass. Clearly identified designated initializers also make tracing through
+and debugging initialization code easier.
+
+Prefer identifying designated initializers by annotating them with designated
+initializer attributes, e.g., `NS_DESIGNATED_INITIALIZER`. Declare designated
+initializers in comments when designated initializer attributes are not
+available. Prefer a single designated initializer unless there is a compelling
+reason or requirement for multiple designated initializers.
+
+Support initializers inherited from superclasses by
+[overriding superclass designated initializers](#Override_Designated_Initializer)
+to ensure that all inherited initializers are directed through subclass
+designated initializers. When there is a compelling reason or requirement that
+an inherited initializer should not be supported, the initializer may be
+annotated with availability attributes (e.g., `NS_UNAVAILABLE`) to discourage
+usage; however, note that availability attributes alone do not completely
+protect against invalid initialization.
+
+<a id="Override_Designated_Initializer"></a>
+
+### Override Designated Initializers
+
+When writing a subclass that requires a new designated initializer, make sure
+you override any designated initializers of the superclass.
+
+When declaring designated initializers on a class, remember that any
+initializers that were considered designated initializers on the superclass
+become convenience initializers of the subclass unless declared otherwise.
+Failure to override superclass designated initializers can result in bugs due to
+invalid initialization using superclass initializers. To avoid invalid
+initialization, ensure convenience initializers call through to a designated
+initializer.
+
+<a id="Overridden_NSObject_Method_Placement"></a>
+
+### Overridden NSObject Method Placement
+
+Put overridden methods of NSObject at the top of an `@implementation`.
+
+This commonly applies to (but is not limited to) the `init...`, `copyWithZone:`,
+and `dealloc` methods. The `init...` methods should be grouped together,
+including those `init...` methods that are not `NSObject` overrides, followed by
+other typical `NSObject` methods such as `description`, `isEqual:`, and `hash`.
+
+Convenience class factory methods for creating instances may precede the
+`NSObject` methods.
+
+<a id="Initialization"></a>
+
+### Initialization
+
+Don't initialize instance variables to `0` or `nil` in the `init` method; doing
+so is redundant.
+
+All instance variables for a newly allocated object are [initialized
+to](https://developer.apple.com/library/mac/documentation/General/Conceptual/CocoaEncyclopedia/ObjectAllocation/ObjectAllocation.html)
+`0` (except for isa), so don't clutter up the init method by re-initializing
+variables to `0` or `nil`.
+
+<a id="Instance_Variables_In_Headers_Should_Be_@protected_or_@private"></a>
+
+### Instance Variables In Headers Should Be @protected or @private
+
+Instance variables should typically be declared in implementation files or
+auto-synthesized by properties. When ivars are declared in a header file, they
+should be marked `@protected` or `@private`.
+
+```objectivec
+// GOOD:
+
+@interface MyClass : NSObject {
+ @protected
+  id _myInstanceVariable;
+}
+@end
+```
+
+<a id="Avoid_+new"></a>
+
+### Do Not Use +new
+
+Do not invoke the `NSObject` class method `new`, nor override it in a subclass.
+`+new` is rarely used and contrasts greatly with initializer usage. Instead, use
+`+alloc` and `-init` methods to instantiate retained objects.
+
+<a id="Keep_the_Public_API_Simple"></a>
+
+### Keep the Public API Simple
+
+Keep your class simple; avoid "kitchen-sink" APIs. If a method doesn't need to
+be public, keep it out of the public interface.
+
+Unlike C++, Objective-C doesn't differentiate between public and private
+methods; any message may be sent to an object. As a result, avoid placing
+methods in the public API unless they are actually expected to be used by a
+consumer of the class. This helps reduce the likelihood they'll be called when
+you're not expecting it. This includes methods that are being overridden from
+the parent class.
+
+Since internal methods are not really private, it's easy to accidentally
+override a superclass's "private" method, thus making a very difficult bug to
+squash. In general, private methods should have a fairly unique name that will
+prevent subclasses from unintentionally overriding them.
+
+<a id="#import_and_#include"></a>
+
+### #import and #include
+
+`#import` Objective-C and Objective-C++ headers, and `#include` C/C++ headers.
+
+C/C++ headers include other C/C++ headers using `#include`. Using `#import`
+on C/C++ headers prevents future inclusions using `#include` and could result in
+unintended compilation behavior.
+
+C/C++ headers should provide their own `#define` guard.
+
+<a id="Order_of_Includes"></a>
+
+### Order of Includes
+
+The standard order for header inclusion is the related header, operating system
+headers, language library headers, and finally groups of headers for other
+dependencies.
+
+The related header precedes others to ensure it has no hidden dependencies.
+For implementation files the related header is the header file.
+For test files the related header is the header containing the tested interface.
+
+Separate each non-empty group of includes with one blank line. Within each group
+the includes should be ordered alphabetically.
+
+Import headers using their path relative to the project's source directory.
+
+```objectivec
+// GOOD:
+
+#import "ProjectX/BazViewController.h"
+
+#import <Foundation/Foundation.h>
+
+#include <unistd.h>
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/integral_types.h"
+#import "base/mac/FOOComplexNumberSupport"
+#include "util/math/mathutil.h"
+
+#import "ProjectX/BazModel.h"
+#import "Shared/Util/Foo.h"
+```
+
+<a id="Use_Umbrella_Headers_for_System_Frameworks"></a>
+
+### Use Umbrella Headers for System Frameworks
+
+Import umbrella headers for system frameworks and system libraries rather than
+include individual files.
+
+While it may seem tempting to include individual system headers from a framework
+such as Cocoa or Foundation, in fact it's less work on the compiler if you
+include the top-level root framework. The root framework is generally
+pre-compiled and can be loaded much more quickly. In addition, remember to use
+`@import` or `#import` rather than `#include` for Objective-C frameworks.
+
+```objectivec
+// GOOD:
+
+@import UIKit;     // GOOD.
+#import <Foundation/Foundation.h>     // GOOD.
+```
+
+```objectivec
+// AVOID:
+
+#import <Foundation/NSArray.h>        // AVOID.
+#import <Foundation/NSString.h>
+...
+```
+
+### Avoid Messaging the Current Object Within Initializers and `-dealloc`
+
+Code in initializers and `-dealloc` should avoid invoking instance methods when
+possible.
+
+Superclass initialization completes before subclass initialization. Until all
+classes have had a chance to initialize their instance state any method
+invocation on self may lead to a subclass operating on uninitialized instance
+state.
+
+A similar issue exists for `-dealloc`, where a method invocation may cause a
+class to operate on state that has been deallocated.
+
+One case where this is less obvious is property accessors. These can be
+overridden just like any other selector. Whenever practical, directly assign to
+and release ivars in initializers and `-dealloc`, rather than rely on accessors.
+
+```objectivec
+// GOOD:
+
+- (instancetype)init {
+  self = [super init];
+  if (self) {
+    _bar = 23;  // GOOD.
+  }
+  return self;
+}
+```
+
+Beware of factoring common initialization code into helper methods:
+
+-   Methods can be overridden in subclasses, either deliberately, or
+    accidentally due to naming collisions.
+-   When editing a helper method, it may not be obvious that the code is being
+    run from an initializer.
+
+```objectivec
+// AVOID:
+
+- (instancetype)init {
+  self = [super init];
+  if (self) {
+    self.bar = 23;  // AVOID.
+    [self sharedMethod];  // AVOID. Fragile to subclassing or future extension.
+  }
+  return self;
+}
+```
+
+```objectivec
+// GOOD:
+
+- (void)dealloc {
+  [_notifier removeObserver:self];  // GOOD.
+}
+```
+
+```objectivec
+// AVOID:
+
+- (void)dealloc {
+  [self removeNotifications];  // AVOID.
+}
+```
+
+There are common cases where a class may need to use properties and methods
+provided by a superclass during initialization. This commonly occurs for classes
+derived from UIKit and AppKit base classes, among other base classes. Use your
+judgement and knowledge of common practice when deciding whether to make an
+exception to this rule.
+
+### Avoid redundant property access
+
+Code should avoid redundant property access. Prefer to assign a property value
+to a local variable when the property value is not expected to change and needs
+to be used multiple times.
+
+```objc
+// GOOD:
+
+UIView *view = self.view;
+UIScrollView *scrollView = self.scrollView;
+[scrollView.leadingAnchor constraintEqualToAnchor:view.leadingAnchor].active = YES;
+[scrollView.trailingAnchor constraintEqualToAnchor:view.trailingAnchor].active = YES;
+```
+
+```objc
+// AVOID:
+
+[self.scrollView.loadingAnchor constraintEqualToAnchor:self.view.loadingAnchor].active = YES;
+[self.scrollView.trailingAnchor constraintEqualToAnchor:self.view.trailingAnchor].active = YES;
+```
+
+When repeatedly referencing chained property invocations, prefer to capture the
+repeated expression in a local variable:
+
+```objc
+// AVOID:
+
+foo.bar.baz.field1 = 10;
+foo.bar.baz.field2 = @"Hello";
+foo.bar.baz.field3 = 2.71828183;
+```
+
+```objc
+// GOOD:
+
+Baz *baz = foo.bar.baz;
+baz.field1 = 10;
+baz.field2 = @"Hello";
+baz.field3 = 2.71828183;
+```
+
+Redundantly accessing the same properties results in multiple message dispatches
+to fetch the same value, and under ARC requires retains and releases of any
+returned objects; the compiler cannot optimize away these extra operations,
+leading to slower execution and substantial increases in binary size.
+
+
+<a id="Mutables_Copies_Ownership"></a>
+
+### Mutables, Copies and Ownership
+
+For [Foundation and other hierarchies containing both immutable and mutable
+subclasses](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/ObjectMutability/ObjectMutability.html)
+a mutable subclass may be substituted for an immutable so long as the
+immutable's contract is honored.
+
+The most common example of this sort of substitution are ownership transfers,
+particularly for return values. In these cases an additional copy is not
+necessary and returning the mutable subclass is more efficient.
+[Callers are expected to treat return values as their declared type](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/ObjectMutability/ObjectMutability.html#//apple_ref/doc/uid/TP40010810-CH5-SW67),
+and thus the return value will be treated as an immutable going forward.
+
+```objectivec
+// GOOD:
+
+- (NSArray *)listOfThings {
+  NSMutableArray *generatedList = [NSMutableArray array];
+  for (NSInteger i = 0; i < _someLimit; i++) {
+    [generatedList addObject:[self thingForIndex:i]];
+  }
+  // Copy not necessary, ownership of generatedList is transferred.
+  return generatedList;
+}
+```
+
+This rule also applies to classes where only a mutable variant exists so long as
+the ownership transfer is clear. Protos are a common example.
+
+```objectivec
+// GOOD:
+
+- (SomeProtoMessage *)someMessageForValue:(BOOL)value {
+  SomeProtoMessage *message = [SomeProtoMessage message];
+  message.someValue = value;
+  return message;
+}
+```
+
+It is not necessary to create a local immutable copy of a mutable type to match
+the method signature of a method being called so long as the mutable argument
+will not change for the duration of the method call. Called methods are expected
+to treat arguments as the declared type, and take
+[defensive copies](#Defensive_Copies)
+([referred to by Apple as "snapshots"](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/ObjectMutability/ObjectMutability.html#//apple_ref/doc/uid/TP40010810-CH5-SW68))
+if they intend to retain those arguments beyond the duration of the call.
+
+```objectivec
+// AVOID:
+
+NSMutableArray *updatedThings = [NSMutableArray array];
+[updatedThings addObject:newThing];
+[_otherManager updateWithCurrentThings:[updatedThings copy]];  // AVOID
+```
+
+<a id="Defensive_Copies"></a>
+<a id="Setters_copy_NSStrings"></a>
+
+### Copy Potentially Mutable Objects
+
+Code receiving and retaining collections or other types with
+[mutable variants](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/ObjectMutability/ObjectMutability.html)
+should consider that the passed object may be mutable, and thus an immutable or
+mutable copy should be retained instead of the original object. In particular,
+initializers and setters
+[should copy instead of retaining objects whose types have mutable variants](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/ObjectMutability/ObjectMutability.html#//apple_ref/doc/uid/TP40010810-CH5-SW68).
+
+Synthesized accessors should use the `copy` keyword to ensure the generated code
+matches these expectations.
+
+NOTE: [The `copy` property keyword only affects the synthesized setter and has
+no effect on
+getters](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/ObjectiveC/Chapters/ocProperties.html#//apple_ref/doc/uid/TP30001163-CH17-SW27).
+Since property keywords have no effect on direct ivar access custom accessors
+must implement the same copy semantics.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, copy) NSString *name;
+@property(nonatomic, copy) NSSet<FilterThing *> *filters;
+
+- (instancetype)initWithName:(NSString *)name
+                     filters:(NSSet<FilterThing *> *)filters {
+  self = [super init];
+  if (self) {
+    _name = [name copy];
+    _filters = [filters copy];
+  }
+  return self;
+}
+
+- (void)setFilters:(NSSet<FilterThing *> *)filters {
+  // Ensure that we retain an immutable collection.
+  _filters = [filters copy];
+}
+```
+
+Similarly, getters must return types that match the contract expectations of the
+immutable types they return.
+
+```objectivec
+// GOOD:
+
+
+@implementation Foo {
+  NSMutableArray<ContentThing *> *_currentContent;
+}
+
+- (NSArray<ContentThing *> *)currentContent {
+  return [_currentContent copy];
+}
+
+```
+
+All Objective-C protos are mutable and typically should be copied rather than
+retained
+[except in clear cases of ownership transfer](#Mutables_Copies_Ownership).
+
+```objectivec
+// GOOD:
+
+- (void)setFooMessage:(FooMessage *)fooMessage {
+  // Copy proto to ensure no other retainer can mutate our value.
+  _fooMessage = [fooMessage copy];
+}
+
+- (FooMessage *)fooMessage {
+  // Copy proto to return so that caller cannot mutate our value.
+  return [_fooMessage copy];
+}
+```
+
+Asynchronous code should copy potentially mutable objects prior to dispatch.
+Objects captured by blocks are retained but not copied.
+
+```objectivec
+// GOOD:
+
+- (void)doSomethingWithThings:(NSArray<Thing *> *)things {
+  NSArray<Thing *> *thingsToWorkOn = [things copy];
+  dispatch_async(_workQueue, ^{
+    for (id<Thing> thing in thingsToWorkOn) {
+      ...
+    }
+  });
+}
+```
+
+NOTE: It is unnecessary to copy objects that do not have mutable variants, e.g.
+`NSURL`, `NSNumber`, `NSDate`, `UIColor`, etc.
+
+<a id="Use_Lightweight_Generics_to_Document_Contained_Types"></a>
+
+### Use Lightweight Generics to Document Contained Types
+
+All projects compiling on Xcode 7 or newer versions should make use of the
+Objective-C lightweight generics notation to type contained objects.
+
+Every `NSArray`, `NSDictionary`, or `NSSet` reference should be declared using
+lightweight generics for improved type safety and to explicitly document usage.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, copy) NSArray<Location *> *locations;
+@property(nonatomic, copy, readonly) NSSet<NSString *> *identifiers;
+
+NSMutableArray<MyLocation *> *mutableLocations = [otherObject.locations mutableCopy];
+```
+
+If the fully-annotated types become complex, consider using a typedef to
+preserve readability.
+
+```objectivec
+// GOOD:
+
+typedef NSSet<NSDictionary<NSString *, NSDate *> *> TimeZoneMappingSet;
+TimeZoneMappingSet *timeZoneMappings = [TimeZoneMappingSet setWithObjects:...];
+```
+
+Use the most descriptive common superclass or protocol available. In the most
+generic case when nothing else is known, declare the collection to be explicitly
+heterogeneous using id.
+
+```objectivec
+// GOOD:
+
+@property(nonatomic, copy) NSArray<id> *unknowns;
+```
+
+<a id="Avoid_Throwing_Exceptions"></a>
+
+### Avoid Throwing Exceptions
+
+Don't `@throw` Objective-C exceptions, but you should be prepared to catch them
+from third-party or OS calls.
+
+This follows the recommendation to use error objects for error delivery in
+[Apple's Introduction to Exception Programming Topics for
+Cocoa](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Exceptions/Exceptions.html).
+
+We do compile with `-fobjc-exceptions` (mainly so we get `@synchronized`), but
+we don't `@throw`. Use of `@try`, `@catch`, and `@finally` are allowed when
+required to properly use 3rd party code or libraries. If you do use them, please
+document exactly which methods you expect to throw.
+
+<a id="nil_Checks"></a>
+
+### `nil` Checks
+
+Avoid `nil` pointer checks that exist only to prevent sending messages to `nil`.
+Sending a message to `nil` [reliably
+returns](http://www.sealiesoftware.com/blog/archive/2012/2/29/objc_explain_return_value_of_message_to_nil.html)
+`nil` as a pointer, zero as an integer or floating-point value, structs
+initialized to `0`, and `_Complex` values equal to `{0, 0}`.
+
+```objectivec
+// AVOID:
+
+if (dataSource) {  // AVOID.
+  [dataSource moveItemAtIndex:1 toIndex:0];
+}
+```
+
+```objectivec
+// GOOD:
+
+[dataSource moveItemAtIndex:1 toIndex:0];  // GOOD.
+```
+
+Note that this applies to `nil` as a message target, not as a parameter value.
+Individual methods may or may not safely handle `nil` parameter values.
+
+Note too that this is distinct from checking C/C++ pointers and block pointers
+against `NULL`, which the runtime does not handle and will cause your
+application to crash. You still need to make sure you do not dereference a
+`NULL` pointer.
+
+### Nullability
+
+Interfaces can be decorated with nullability annotations to describe how the
+interface should be used and how it behaves. Use of nullability regions (e.g.,
+`NS_ASSUME_NONNULL_BEGIN` and `NS_ASSUME_NONNULL_END`) and explicit nullability
+annotations are both accepted. Prefer using the `_Nullable` and `_Nonnull`
+keywords over the `__nullable` and `__nonnull` keywords. For Objective-C methods
+and properties prefer using the context-sensitive, non-underscored keywords,
+e.g., `nonnull` and `nullable`.
+
+```objectivec
+// GOOD:
+
+/** A class representing an owned book. */
+@interface GTMBook : NSObject
+
+/** The title of the book. */
+@property(nonatomic, readonly, copy, nonnull) NSString *title;
+
+/** The author of the book, if one exists. */
+@property(nonatomic, readonly, copy, nullable) NSString *author;
+
+/** The owner of the book. Setting nil resets to the default owner. */
+@property(nonatomic, copy, null_resettable) NSString *owner;
+
+/** Initializes a book with a title and an optional author. */
+- (nonnull instancetype)initWithTitle:(nonnull NSString *)title
+                               author:(nullable NSString *)author
+    NS_DESIGNATED_INITIALIZER;
+
+/** Returns nil because a book is expected to have a title. */
+- (nullable instancetype)init;
+
+@end
+
+/** Loads books from the file specified by the given path. */
+NSArray<GTMBook *> *_Nullable GTMLoadBooksFromFile(NSString *_Nonnull path);
+```
+
+```objectivec
+// AVOID:
+
+NSArray<GTMBook *> *__nullable GTMLoadBooksFromTitle(NSString *__nonnull path);
+```
+
+Do not assume that a pointer is not null based on a nonnull qualifier, because
+the compiler only checks a subset of such cases, and does not guarantee that the
+pointer is not null. Avoid intentionally violating nullability semantics
+of function, method, and property declarations.
+
+<a id="BOOL_Pitfalls"></a>
+
+### BOOL Pitfalls
+
+<a id="BOOL_Expressions_Conversions"></a>
+#### BOOL Expressions and Conversions
+
+Be careful when converting general integral values to `BOOL`. Avoid comparing
+directly with `YES` or comparing multiple `BOOL` values with comparison
+operators.
+
+`BOOL` on some Apple platforms (notably Intel macOS, watchOS, and 32-bit iOS)
+is defined as a signed `char`, so it may have values other than `YES` (`1`) and
+`NO` (`0`). Do not cast or convert general integral values directly to `BOOL`.
+
+Common mistakes include casting or converting an array's size, a pointer value,
+or the result of a bitwise logic operation to a `BOOL`. These operations can
+depend on the value of the last byte of the integer value and result in an
+unexpected `NO` value. Operations with NS_OPTIONS values and flag masking are
+especially common errors.
+
+When converting a general integral value to a `BOOL`, use conditional operators
+to return a `YES` or `NO` value.
+
+You can safely interchange and convert `BOOL`, `_Bool` and `bool` (see C++ Std
+4.7.4, 4.12 and C99 Std 6.3.1.2). Use `BOOL` in Objective-C method signatures.
+
+Using logical operators (`&&`, `||` and `!`) with `BOOL` is also valid and will
+return values that can be safely converted to `BOOL` without the need for a
+conditional operator.
+
+```objectivec
+// AVOID:
+
+- (BOOL)isBold {
+  return [self fontTraits] & NSFontBoldTrait;  // AVOID.
+}
+- (BOOL)isValid {
+  return [self stringValue];  // AVOID.
+}
+- (BOOL)isLongEnough {
+  return (BOOL)([self stringValue].count);  // AVOID.
+}
+```
+
+```objectivec
+// GOOD:
+
+- (BOOL)isBold {
+  return ([self fontTraits] & NSFontBoldTrait) ? YES : NO;
+}
+- (BOOL)isValid {
+  return [self stringValue] != nil;
+}
+- (BOOL)isLongEnough {
+  return [self stringValue].count > 0;
+}
+- (BOOL)isEnabled {
+  return [self isValid] && [self isBold];
+}
+```
+
+Don't directly compare `BOOL` variables directly with `YES`. Not only is
+it harder to read for those well-versed in C, but the first point above
+demonstrates that return values may not always be what you expect.
+
+```objectivec
+// AVOID:
+
+BOOL great = [foo isGreat];
+if (great == YES) {  // AVOID.
+  // ...be great!
+}
+```
+
+```objectivec
+// GOOD:
+
+BOOL great = [foo isGreat];
+if (great) {         // GOOD.
+  // ...be great!
+}
+```
+
+Don't directly compare `BOOL` values using comparison operators. `BOOL`
+values that are true may not be equal. Use logical operators in place
+of bitwise comparisons of `BOOL` values.
+
+```objectivec
+// AVOID:
+
+if (oldBOOLValue != newBOOLValue) {  // AVOID.
+  // ... code that should only run when the value changes.
+}
+```
+
+```objectivec
+// GOOD:
+
+if ((!oldBoolValue && newBoolValue) || (oldBoolValue && !newBoolValue)) {  // GOOD.
+  // ... code that should only run when the value changes.
+}
+
+// GOOD, the results of logical operators on BOOLs are safe to compare.
+if (!oldBoolValue != !newBoolValue) {
+  // ... code that should only run when the value changes.
+}
+```
+
+#### BOOL Literals
+
+The [BOOL NSNumber literals](https://clang.llvm.org/docs/ObjectiveCLiterals.html#nsnumber-literals)
+are `@YES` and `@NO` which are equivalent to `[NSNumber numberWithBool:...]`.
+
+Avoid using [boxed expressions](https://clang.llvm.org/docs/ObjectiveCLiterals.html#boxed-expressions)
+to create BOOL values, including simple expressions like `@(YES)`.
+Boxed expressions suffer from [the same pitfalls as other BOOL expressions]
+(#BOOL_Expressions_Conversions) as boxing general integral values can
+produce true or false `NSNumbers` that are not equal to `@YES` and `@NO`.
+
+When converting a general integral value to a BOOL literal, use conditional
+operators to convert to `@YES` or `@NO`. Do not embed a conditional operator
+inside a boxed expression as this is equivalent to boxing general integral
+values even when the result of the operation is a BOOL.
+
+```objectivec
+// AVOID:
+
+[_boolArray addValue:@(YES)];  // AVOID boxing even in simple cases.
+NSNumber *isBold = @(self.fontTraits & NSFontBoldTrait);  // AVOID.
+NSNumber *hasContent = @([self stringValue].length);  // AVOID.
+NSNumber *isValid = @([self stringValue]);  // AVOID.
+NSNumber *isStringNotNil = @([self stringValue] ? YES : NO);  // AVOID.
+```
+
+```objectivec
+// GOOD:
+
+[_boolArray addValue:@YES];  // GOOD.
+NSNumber *isBold = self.fontTraits & NSFontBoldTrait ? @YES : @NO;  // GOOD.
+NSNumber *hasContent = [self stringValue].length ? @YES : @NO;  // GOOD.
+NSNumber *isValid = [self stringValue] ? @YES : @NO;  // GOOD.
+NSNumber *isStringNotNil = [self stringValue] ? @YES : @NO;  // GOOD.
+```
+
+<a id="Interfaces_Without_Instance_Variables"></a>
+<a id="interfaces-without-instance-variables"></a>
+
+### Containers Without Instance Variables
+
+Omit the empty set of braces on interfaces, class extensions, and
+implementations without any instance variable declarations.
+
+```objectivec
+// GOOD:
+
+@interface MyClass : NSObject
+// Does a lot of stuff.
+- (void)fooBarBam;
+@end
+
+@interface MyClass ()
+- (void)classExtensionMethod;
+@end
+
+@implementation MyClass
+// Actual implementation.
+@end
+```
+
+```objectivec
+// AVOID:
+
+@interface MyClass : NSObject {
+}
+// Does a lot of stuff.
+- (void)fooBarBam;
+@end
+
+@interface MyClass () {
+}
+- (void)classExtensionMethod;
+@end
+
+@implementation MyClass {
+}
+// Actual implementation.
+@end
+```
+
+<a id="Cocoa_Patterns"></a>
+
+## Cocoa Patterns
+
+<a id="Delegate_Pattern"></a>
+
+### Delegate Pattern
+
+Delegates, target objects, and block pointers should not be retained when doing
+so would create a retain cycle.
+
+To avoid causing a retain cycle, a delegate or target pointer should be released
+as soon as it is clear there will no longer be a need to message the object.
+
+If there is no clear time at which the delegate or target pointer is no longer
+needed, the pointer should only be retained weakly.
+
+Block pointers cannot be retained weakly. To avoid causing retain cycles in the
+client code, block pointers should be used for callbacks only where they can be
+explicitly released after they have been called or once they are no longer
+needed. Otherwise, callbacks should be done via weak delegate or target
+pointers.
+
+<a id="Objective-C++"></a>
+
+## Objective-C++
+
+<a id="Style_Matches_the_Language"></a>
+
+### Style Matches the Language
+
+Within an Objective-C++ source file, follow the style for the language of the
+function or method you're implementing. In order to minimize clashes between the
+differing naming styles when mixing Cocoa/Objective-C and C++, follow the style
+of the method being implemented.
+
+For code in an `@implementation` block, use the Objective-C naming rules. For
+code in a method of a C++ class, use the C++ naming rules.
+
+For code in an Objective-C++ file outside of a class implementation, be
+consistent within the file.
+
+```objectivec++
+// GOOD:
+
+// file: cross_platform_header.h
+
+class CrossPlatformAPI {
+ public:
+  ...
+  int DoSomethingPlatformSpecific();  // impl on each platform
+ private:
+  int an_instance_var_;
+};
+
+// file: mac_implementation.mm
+#include "cross_platform_header.h"
+
+/** A typical Objective-C class, using Objective-C naming. */
+@interface MyDelegate : NSObject {
+ @private
+  int _instanceVar;
+  CrossPlatformAPI* _backEndObject;
+}
+
+- (void)respondToSomething:(id)something;
+
+@end
+
+@implementation MyDelegate
+
+- (void)respondToSomething:(id)something {
+  // bridge from Cocoa through our C++ backend
+  _instanceVar = _backEndObject->DoSomethingPlatformSpecific();
+  NSString* tempString = [NSString stringWithFormat:@"%d", _instanceVar];
+  NSLog(@"%@", tempString);
+}
+
+@end
+
+/** The platform-specific implementation of the C++ class, using C++ naming. */
+int CrossPlatformAPI::DoSomethingPlatformSpecific() {
+  NSString* temp_string = [NSString stringWithFormat:@"%d", an_instance_var_];
+  NSLog(@"%@", temp_string);
+  return [temp_string intValue];
+}
+```
+
+Projects may opt to use an 80 column line length limit for consistency with
+Google's C++ style guide.
+
+<a id="Spacing_and_Formatting"></a>
+
+## Spacing and Formatting
+
+<a id="Spaces_vs._Tabs"></a>
+
+### Spaces vs. Tabs
+
+Use only spaces, and indent 2 spaces at a time. We use spaces for indentation.
+Do not use tabs in your code.
+
+You should set your editor to emit spaces when you hit the tab key, and to trim
+trailing spaces on lines.
+
+<a id="Line_Length"></a>
+
+### Line Length
+
+The maximum line length for Objective-C files is 100 columns.
+
+<a id="Method_Declarations_and_Definitions"></a>
+
+### Method Declarations and Definitions
+
+One space should be used between the `-` or `+` and the return type. In general,
+there should be no spacing in the parameter list except between parameters.
+
+Methods should look like this:
+
+```objectivec
+// GOOD:
+
+- (void)doSomethingWithString:(NSString *)theString {
+  ...
+}
+```
+
+The spacing before the asterisk is optional. When adding new code, be consistent
+with the surrounding file's style.
+
+If a method declaration does not fit on a single line, put each parameter on its
+own line. All lines except the first should be indented at least four spaces.
+Colons before parameters should be aligned on all lines. If the colon before the
+parameter on the first line of a method declaration is positioned such that
+colon alignment would cause indentation on a subsequent line to be less than
+four spaces, then colon alignment is only required for all lines except the
+first. If a parameter declared after the `:` in a method declaration or
+definition would cause the line limit to be exceeded, wrap the content to the
+next line indented by at least four spaces.
+
+```objectivec
+// GOOD:
+
+- (void)doSomethingWithFoo:(GTMFoo *)theFoo
+                      rect:(NSRect)theRect
+                  interval:(float)theInterval {
+  ...
+}
+
+- (void)shortKeyword:(GTMFoo *)theFoo
+            longerKeyword:(NSRect)theRect
+    someEvenLongerKeyword:(float)theInterval
+                    error:(NSError **)theError {
+  ...
+}
+
+- (id<UIAdaptivePresentationControllerDelegate>)
+    adaptivePresentationControllerDelegateForViewController:(UIViewController *)viewController;
+
+- (void)presentWithAdaptivePresentationControllerDelegate:
+    (id<UIAdaptivePresentationControllerDelegate>)delegate;
+
+- (void)updateContentHeaderViewForExpansionToContentOffset:(CGPoint)contentOffset
+                                            withController:
+                                                (GTMCollectionExpansionController *)controller;
+
+```
+
+### Function Declarations and Definitions
+
+Prefer putting the return type on the same line as the function name and append
+all parameters on the same line if they will fit. Wrap parameter lists which do
+not fit on a single line as you would wrap arguments in a [function
+call](#Function_Calls).
+
+```objectivec
+// GOOD:
+
+NSString *GTMVersionString(int majorVersion, int minorVersion) {
+  ...
+}
+
+void GTMSerializeDictionaryToFileOnDispatchQueue(
+    NSDictionary<NSString *, NSString *> *dictionary,
+    NSString *filename,
+    dispatch_queue_t queue) {
+  ...
+}
+```
+
+Function declarations and definitions should also satisfy the following
+conditions:
+
+*   The opening parenthesis must always be on the same line as the function
+    name.
+*   If you cannot fit the return type and the function name on a single line,
+    break between them and do not indent the function name.
+*   There should never be a space before the opening parenthesis.
+*   There should never be a space between function parentheses and parameters.
+*   The open curly brace is always on the end of the last line of the function
+    declaration, not the start of the next line.
+*   The close curly brace is either on the last line by itself or on the same
+    line as the open curly brace.
+*   There should be a space between the close parenthesis and the open curly
+    brace.
+*   All parameters should be aligned if possible.
+*   Function scopes should be indented 2 spaces.
+*   Wrapped parameters should have a 4 space indent.
+
+<a id="Conditionals"></a>
+
+### Conditionals
+
+Include a space after `if`, `while`, `for`, and `switch`, and around comparison
+operators.
+
+```objectivec
+// GOOD:
+
+for (int i = 0; i < 5; ++i) {
+}
+
+while (test) {};
+```
+
+Braces may be omitted when a loop body or conditional statement fits on a single
+line.
+
+```objectivec
+// GOOD:
+
+if (hasSillyName) LaughOutLoud();
+
+for (int i = 0; i < 10; i++) {
+  BlowTheHorn();
+}
+```
+
+```objectivec
+// AVOID:
+
+if (hasSillyName)
+  LaughOutLoud();               // AVOID.
+
+for (int i = 0; i < 10; i++)
+  BlowTheHorn();                // AVOID.
+```
+
+If an `if` clause has an `else` clause, both clauses should use braces.
+
+```objectivec
+// GOOD:
+
+if (hasBaz) {
+  foo();
+} else {  // The else goes on the same line as the closing brace.
+  bar();
+}
+```
+
+```objectivec
+// AVOID:
+
+if (hasBaz) foo();
+else bar();        // AVOID.
+
+if (hasBaz) {
+  foo();
+} else bar();      // AVOID.
+```
+
+Intentional fall-through to the next case should be documented with a comment
+unless the case has no intervening code before the next case.
+
+```objectivec
+// GOOD:
+
+switch (i) {
+  case 1:
+    ...
+    break;
+  case 2:
+    j++;
+    // Falls through.
+  case 3: {
+    int k;
+    ...
+    break;
+  }
+  case 4:
+  case 5:
+  case 6: break;
+}
+```
+
+<a id="Expressions"></a>
+
+### Expressions
+
+Use a space around binary operators and assignments. Omit a space for a unary
+operator. Do not add spaces inside parentheses.
+
+```objectivec
+// GOOD:
+
+x = 0;
+v = w * x + y / z;
+v = -y * (x + z);
+```
+
+Factors in an expression may omit spaces.
+
+```objectivec
+// GOOD:
+
+v = w*x + y/z;
+```
+
+<a id="Method_Invocations"></a>
+
+### Method Invocations
+
+Method invocations should be formatted much like method declarations.
+
+When there's a choice of formatting styles, follow the convention already used
+in a given source file. Invocations should have all arguments on one line:
+
+```objectivec
+// GOOD:
+
+[myObject doFooWith:arg1 name:arg2 error:arg3];
+```
+
+or have one argument per line, with colons aligned:
+
+```objectivec
+// GOOD:
+
+[myObject doFooWith:arg1
+               name:arg2
+              error:arg3];
+```
+
+Don't use any of these styles:
+
+```objectivec
+// AVOID:
+
+[myObject doFooWith:arg1 name:arg2  // some lines with >1 arg
+              error:arg3];
+
+[myObject doFooWith:arg1
+               name:arg2 error:arg3];
+
+[myObject doFooWith:arg1
+          name:arg2  // aligning keywords instead of colons
+          error:arg3];
+```
+
+As with declarations and definitions, when the first keyword is shorter than the
+others, indent the later lines by at least four spaces, maintaining colon
+alignment:
+
+```objectivec
+// GOOD:
+
+[myObj short:arg1
+          longKeyword:arg2
+    evenLongerKeyword:arg3
+                error:arg4];
+```
+
+Invocations containing multiple inlined blocks may have their parameter names
+left-aligned at a four space indent.
+
+<a id="Function_Calls"></a>
+
+### Function Calls
+
+Function calls should include as many parameters as fit on each line, except
+where shorter lines are needed for clarity or documentation of the parameters.
+
+Continuation lines for function parameters may be indented to align with the
+opening parenthesis, or may have a four-space indent.
+
+```objectivec
+// GOOD:
+
+CFArrayRef array = CFArrayCreate(kCFAllocatorDefault, objects, numberOfObjects,
+                                 &kCFTypeArrayCallBacks);
+
+NSString *string = NSLocalizedStringWithDefaultValue(@"FEET", @"DistanceTable",
+    resourceBundle,  @"%@ feet", @"Distance for multiple feet");
+
+UpdateTally(scores[x] * y + bases[x],  // Score heuristic.
+            x, y, z);
+
+TransformImage(image,
+               x1, x2, x3,
+               y1, y2, y3,
+               z1, z2, z3);
+```
+
+Use local variables with descriptive names to shorten function calls and reduce
+nesting of calls.
+
+```objectivec
+// GOOD:
+
+double scoreHeuristic = scores[x] * y + bases[x];
+UpdateTally(scoreHeuristic, x, y, z);
+```
+
+<a id="Exceptions"></a>
+
+### Exceptions
+
+Format exceptions with `@catch` and `@finally` labels on the same line as the
+preceding `}`. Add a space between the `@` label and the opening brace (`{`), as
+well as between the `@catch` and the caught object declaration. If you must use
+Objective-C exceptions, format them as follows. However, see [Avoid Throwing
+Exceptions](#Avoid_Throwing_Exceptions) for reasons why you should not be using
+exceptions.
+
+```objectivec
+// GOOD:
+
+@try {
+  foo();
+} @catch (NSException *ex) {
+  bar(ex);
+} @finally {
+  baz();
+}
+```
+
+<a id="Function_Length"></a>
+
+### Function Length
+
+Prefer small and focused functions.
+
+Long functions and methods are occasionally appropriate, so no hard limit is
+placed on function length. If a function exceeds about 40 lines, think about
+whether it can be broken up without harming the structure of the program.
+
+Even if your long function works perfectly now, someone modifying it in a few
+months may add new behavior. This could result in bugs that are hard to find.
+Keeping your functions short and simple makes it easier for other people to read
+and modify your code.
+
+When updating legacy code, consider also breaking long functions into smaller
+and more manageable pieces.
+
+<a id="Vertical_Whitespace"></a>
+
+### Vertical Whitespace
+
+Use vertical whitespace sparingly.
+
+To allow more code to be easily viewed on a screen, avoid putting blank lines
+just inside the braces of functions.
+
+Limit blank lines to one or two between functions and between logical groups of
+code.
+
+<a id="Objective-C_Style_Exceptions"></a>
+
+## Objective-C Style Exceptions
+
+<a id="Indicating_style_exceptions"></a>
+
+### Indicating style exceptions
+
+Lines of code that are not expected to adhere to these style recommendations
+require `// NOLINT` at the end of the line or `// NOLINTNEXTLINE` at the end of
+the previous line. Sometimes it is required that parts of Objective-C code must
+ignore these style recommendations (for example code may be machine generated or
+code constructs are such that its not possible to style correctly).
+
+A `// NOLINT` comment on that line or `// NOLINTNEXTLINE` on the previous line
+can be used to indicate to the reader that code is intentionally ignoring style
+guidelines. In addition these annotations can also be picked up by automated
+tools such as linters and handle code correctly. Note that there is a single
+space between `//` and `NOLINT*`.