纽约时报移动团队 Objective-C 项目风格指南中文版.zip

# 注：此文档并未与官方同步翻译，仅供参考。 # 译者的话 代码风格的重要性对于一个团队和项目来说不言而喻。网上有许多 Objective-C 的代码风格，但这份简洁而又最符合苹果的规范，同时有助于养成良好的代码习惯，也是我们团队一直遵循的代码风格。 原文在[这里][original_link]。 本人才疏学浅，如果有任何翻译不当欢迎在 [Issues][Issues_link] 中反馈或者直接 [Fork][Fork_link] 。 [original_link]:https://github.com/NYTimes/objective-c-style-guide [Issues_link]:https://github.com/VincentSit/NYTimes-Objective-C-Style-Guide-ZH/issues [Fork_link]:https://github.com/NYTimes/objective-c-style-guide/fork ---- # 纽约时报 移动团队 Objective-C 规范指南 这份规范指南概括了纽约时报 iOS 团队的代码约定。 ## 介绍 关于这个编程语言的所有规范，如果这里没有写到，那就在苹果的文档里： * [Objective-C 编程语言][Introduction_1] * [Cocoa 基本原理指南][Introduction_2] * [Cocoa 编码指南][Introduction_3] * [iOS 应用编程指南][Introduction_4] [Introduction_1]:http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/ObjectiveC/Introduction/introObjectiveC.html [Introduction_2]:https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CocoaFundamentals/Introduction/Introduction.html [Introduction_3]:https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html [Introduction_4]:http://developer.apple.com/library/ios/#documentation/iphone/conceptual/iphoneosprogrammingguide/Introduction/Introduction.html ## 目录 * [点语法](#点语法) * [间距](#间距) * [条件判断](#条件判断) * [三目运算符](#三目运算符) * [错误处理](#错误处理) * [方法](#方法) * [变量](#变量) * [命名](#命名) * [注释](#注释) * [Init 和 Dealloc](#init-和-dealloc) * [字面量](#字面量) * [CGRect 函数](#CGRect-函数) * [常量](#常量) * [枚举类型](#枚举类型) * [位掩码](#位掩码) * [私有属性](#私有属性) * [图片命名](#图片命名) * [布尔](#布尔) * [单例](#单例) * [导入](#导入) * [Xcode 工程](#Xcode-工程) ## 点语法 应该 **始终** 使用点语法来访问或者修改属性，访问其他实例时首选括号。 **推荐：** ```objc view.backgroundColor = [UIColor orangeColor]; [UIApplication sharedApplication].delegate; ``` **反对：** ```objc [view setBackgroundColor:[UIColor orangeColor]]; UIApplication.sharedApplication.delegate; ``` ## 间距 * 一个缩进使用 4 个空格，永远不要使用制表符（tab）缩进。请确保在 Xcode 中设置了此偏好。 * 方法的大括号和其他的大括号（`if`/`else`/`switch`/`while` 等等）始终和声明在同一行开始，在新的一行结束。 **推荐：** ```objc if (user.isHappy) { // Do something } else { // Do something else } ``` * 方法之间应该正好空一行，这有助于视觉清晰度和代码组织性。在方法中的功能块之间应该使用空白分开，但往往可能应该创建一个新的方法。 * `@synthesize` 和 `@dynamic` 在实现中每个都应该占一个新行。 ## 条件判断 条件判断主体部分应该始终使用大括号括住来防止[出错][Condiationals_1]，即使它可以不用大括号（例如它只需要一行）。这些错误包括添加第二行（代码）并希望它是 if 语句的一部分时。还有另外一种[更危险的][Condiationals_2]，当 if 语句里面的一行被注释掉，下一行就会在不经意间成为了这个 if 语句的一部分。此外，这种风格也更符合所有其他的条件判断，因此也更容易检查。 **推荐：** ```objc if (!error) { return success; } ``` **反对：** ```objc if (!error) return success; ``` 或 ```objc if (!error) return success; ``` [Condiationals_1]:(https://github.com/NYTimes/objective-c-style-guide/issues/26#issuecomment-22074256) [Condiationals_2]:http://programmers.stackexchange.com/a/16530 ### 三目运算符 三目运算符，? ，只有当它可以增加代码清晰度或整洁时才使用。单一的条件都应该优先考虑使用。多条件时通常使用 if 语句会更易懂，或者重构为实例变量。 **推荐：** ```objc result = a > b ? x : y; ``` **反对：** ```objc result = a > b ? x = c > d ? c : d : y; ``` ## 错误处理 当引用一个返回错误参数（error parameter）的方法时，应该针对返回值，而非错误变量。 **推荐：** ```objc NSError *error; if (![self trySomethingWithError:&error]) { // 处理错误 } ``` **反对：** ```objc NSError *error; [self trySomethingWithError:&error]; if (error) { // 处理错误 } ``` 一些苹果的 API 在成功的情况下会写一些垃圾值给错误参数（如果非空），所以针对错误变量可能会造成虚假结果（以及接下来的崩溃）。 ## 方法 在方法签名中，在 -/+ 符号后应该有一个空格。方法片段之间也应该有一个空格。 **推荐：** ```objc - (void)setExampleText:(NSString *)text image:(UIImage *)image; ``` ## 变量 变量名应该尽可能命名为描述性的。除了 `for()` 循环外，其他情况都应该避免使用单字母的变量名。 星号表示指针属于变量，例如：`NSString *text` 不要写成 `NSString* text` 或者 `NSString * text` ，常量除外。 尽量定义属性来代替直接使用实例变量。除了初始化方法（`init`， `initWithCoder:`，等）， `dealloc` 方法和自定义的 setters 和 getters 内部，应避免直接访问实例变量。更多有关在初始化方法和 dealloc 方法中使用访问器方法的信息，参见[这里][Variables_1]。 **推荐：** ```objc @interface NYTSection: NSObject @property (nonatomic) NSString *headline; @end ``` **反对：** ```objc @interface NYTSection : NSObject { NSString *headline; } ``` [Variables_1]:https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmPractical.html#//apple_ref/doc/uid/TP40004447-SW6 #### 变量限定符 当涉及到[在 ARC 中被引入][Variable_Qualifiers_1]变量限定符时， 限定符 (`__strong`, `__weak`, `__unsafe_unretained`, `__autoreleasing`) 应该位于星号和变量名之间，如：`NSString * __weak text`。 [Variable_Qualifiers_1]:(https://developer.apple.com/library/ios/releasenotes/objectivec/rn-transitioningtoarc/Introduction/Introduction.html#//apple_ref/doc/uid/TP40011226-CH1-SW4) ## 命名 尽可能遵守苹果的命名约定，尤其那些涉及到[内存管理规则][Naming_1]，（[NARC][Naming_2]）的。 长的和描述性的方法名和变量名都不错。 **推荐：** ```objc UIButton *settingsButton; ``` **反对：** ```objc UIButton *setBut; ``` 类名和常量应该始终使用三个字母的前缀（例如 `NYT`），但 Core Data 实体名称可以省略。为了代码清晰，常量应该使用相关类的名字作为前缀并使用驼峰命名法。 **推荐：** ```objc static const NSTimeInterval NYTArticleViewControllerNavigationFadeAnimationDuration = 0.3; ``` **反对：** ```objc static const NSTimeInterval fadetime = 1.7; ``` 属性和局部变量应该使用驼峰命名法并且首字母小写。 为了保持一致，实例变量应该使用驼峰命名法命名，并且首字母小写，以下划线为前缀。这与 LLVM 自动合成的实例变量相一致。 **如果 LLVM 可以自动合成变量，那就让它自动合成。** **推荐：** ```objc @synthesize descriptiveVariableName = _descriptiveVariableName; ``` **反对：** ```objc id varnm; ``` [Naming_1]:https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/MemoryMgmt.html [Naming_2]:http://stackoverflow.com/a/2865194/340508 ## 注释 当需要的时候，注释应该被用来解释 **为什么**