OC -- Objective-C语言编码规范

高质量iOS编程指南系列一：Objective-C语言编码规范 - Michael Xia

原文  http://www.cnblogs.com/xdream86/p/3309345.html

  本文由海水的味道编译整理，转载请注明译者和出处，请勿用于商业用途！

点标记语法

属性和幂等方法（多次调用和一次调用返回的结果相同）使用点标记语法访问，其他的情况使用方括号标记语法。

良好的风格：

view.backgroundColor = [UIColor orangeColor];

[UIApplication sharedApplication].delegate;

不良的风格：

[view setBackgroundColor:[UIColor orangeColor]];

UIApplication.sharedApplication.delegate;

间距

二元运算符 和参数之间需要放置一个空格， 一元运算符 、 强制类型转换 和参数之间不放置空格。 关键字之后圆括号之前 需要放置一个空格。

void *ptr = &value + 10 * 3;

NewType a = (NewType) b;

 

for ( int i = 0; i < 10; i ++ ) {

    doCoolThings();

}

数组和字典类型的字面值的 方括号两边 各放置一个空格。

NSArray *theShit = @[ @1 , @2, @3 ] ;

字典字面值的键和冒号之间没有空格，冒号和值之间有一个空格。

NSDictionary *keyedShit = @{ GHDidCreateStyleGuide: @YES };

C函数声明中， 左括号的前面 不保留空格，并且函数名应该像类一样带有命名空间标识。

良好的风格：

void RNCwesomeFunctio n( BOOL hasSomeArgs);

长的字面值应被拆分为多行。

良好的风格：

NSArray *theShit = @[

    @"Got some long string objects in here.",

    [AndSomeModelObjects too],

    @"Moar strings."

];

 

NSDictionary *keyedShit = @{

    @"this.key": @"corresponds to this value",

    @"otherKey": @"remoteData.payload",

    @"some": @"more",

    @"JSON": @"keys",

    @"and": @"stuff",

};

每一行代码使用 4个空格缩进。不使用tab缩进。下图是在Xcode的Preferences进行缩进设置的截图。

 

 

方法签名以及其他关键字（ if/else/switch/while等）后面跟随的左花括号总是和语句出现 于同一行，而右花括号独占一行。

良好的风格：

if (user.isHappy) {

//Do something

}

else {

//Do something else

}

如果一个方法内有多个功能区域，可以使用空行分隔功能区域。

每一行代码不要超过 100 个字符。

每一个方法之前都有一个 99 字符宽的注释行，注释行相对于使用空行更能提高代码的辨识度，当一行代码很长的时候，注释行也起到了越界检测的作用。注释行：

///

条件语句

所有的逻辑块必须使用花括号包围，即使条件体只需编写一行代码也必须使用花括号。

良好的风格做法： 

if (!error) {

    return success;

}

不良的风格：

if (!error)

    return success;

或：

if (!error) return success;

三元运算符

长的三元运算符应使用圆括号括起来。三元运算符仅用于赋值和做参数。

Blah *a = (stuff == thing ? foo : bar);

合并的 nil 三元运算符应该尽量避免。

不良的风格：

Blah *b = thingThatCouldBeNil ?: defaultValue;

多分支条件应该使用 if 语句或重构为实例变量。

良好的风格：

result = a > b ? x : y;

不良的风格：

result = a > b ? x = c > d ? c : d : y;

异常和错误处理

不要在流控制语句中使用异常（ NSException ）。

异常仅用于表明程序员的错误。

为了表明一个错误，使用 NSError * 。

当一个方法通过引用返回一个错误参数，应该检测返回值的状态，而不是错误参数的状态。

良好的风格：

NSError *error;

if (![self trySomethingWithError:&error]) {

    // Handle Error

}

不良的风格：

NSError *error;

[self trySomethingWithError:&error];

if (error) {

    // Handle Error

}

在方法执行成功的情况下赋值非 Null 值给错误参数，会使路径跳转到假条件分支（随后程序奔溃）。

代理

除了继承一个类或实现一个协议，否则在头文件中仅使用类声明 @class 指令，不用 #import 导入类头文件。

如果一个 delegate 只有几个方法，比如只是提交和取消，推荐使用 block 编写动作响应代码。

由于代理方法的声明一般都很长，所以必须将代理对象和其他的协议对象放在实例变量定义的下面，否则实例变量定义的对齐方式将会被打乱掉。

当需要实现多个协议的时候，将每一个协议名拆分到单独的行。

良好的风格：

@interface CustomModelViewController : TTViewController <

  TTModelDelegate,

  TTURLRequestDelegate

> {

方法

一个方法的命名首先描述返回什么，接着是什么情况下被返回。方法签名中冒号的前面描述传入参数的类型。以下类方法和实例方法命名的格式语法：

[object/class thing+ condition ];

[object/class thing+ input :input];

[object/class thing+ identifer :input];

Cocoa 命名举例：

realPath    = [path     string ByExpandingTildeInPath ];

fullString  = [string   string ByAppendingString :@"Extra Text"];

object      = [array    object AtIndex :3];

// 类方法

newString   = [NSString string WithFormat :@"%f",1.5];

newArray    = [NSArray  array WithObject :newString];

良好的自定义方法命名风格：

recipients  = [email    recipients SortedByLastName ];

newEmail    = [CDCEmail email WithSubjectLine :@"Extra Text"];

emails      = [mailbox  messages ReceivedAfterDate :yesterdayDate];

当需要获取对象值的另一种类型的时候，方法命名的格式语法如下：

[object adjective +thing];

[object adjective +thing+ condition ];

[object adjective +thing+ input :input];

良好的自定义方法命名风格：

capitalized = [name    capitalized String];

rate        = [number  float Value];

newString   = [string  decomposed String WithCanonicalMapping ];

subarray    = [array   sub array WithRange :segment];

方法签名尽量做到含义明确。

不良的风格：

-sortInfo  // 是返回排序结果还是给 info 做排序

-refreshTimer  // 返回一个用于刷新的定时器还是刷新定时器

-update  // 更新什么，如何更新

良好的风格：

-currentSortInfo      // "current" 清楚地修饰了名词 SortInfo

-refreshDefaultTimer  // refresh 是一个动词。

-updateMenuItemTitle  // 一个正在发生的动作

方法类型修饰符 +/- 后要放置一个空格，各参数名之间也要放置一个空格。

良好的风格：

- (void)setExampleText:(NSString *)text image:(UIImage *)image;

如果方法的命名特别长，将方法名拆分成多行。

良好的风格：

color = [NSColor colorWithCalibratedHue: 0.10

                               saturation: 0.82

                              brightness: 0.89

                                    alpha: 1.00];

不要将私有的实例变量和方法声明在头文件中，应将私有变量和方法声明在实现文件的类扩展内。

不良的风格：

//MyViewController.h 文件

@interface MyViewController : UIViewController<

 UITalbeViewDataSource,

 UITableViewDelegate> {

 @private:

  UITableView *_myTableView;  // 私有实例变量

}

// 内部使用的属性

@property (nonatomic,strong) NSNumber *variableUsedInternally;

- (void)sortName;  // 只用于内部使用的方法

@end

良好的风格：

//MyViewController.m 文件使用类扩展

@interface MyViewController()<

 UITalbeViewDataSource,

 UITableViewDelegate> {

  UITableView *_myTableView;

// 外部需要访问的实例变量声明为属性，不需要外部访问的声明为实例变量

  NSNumber * variableUsedInternally;

}

// 从 Xcode4.3 开始，可以不写方法的前置声明， Interface Builder 和Storyboard 仍然可以找到方法的定义

@end

构造函数通常应该返回实例类型而不是 id 类型

参数

方法参数名前一般使用的前缀包括“ the ”、“ an ”、“ new ”。

良好的风格：

- (void)       setTitle:           (NSString *)   aTitle;

- (void)       setName:            (NSString *)   newName;

- (id)         keyForOption:       (CDCOption *)  anOption

- (NSArray *)  emailsForMailbox:   (CDCMailbox *) theMailbox;

- (CDCEmail *) emailForRecipients: (NSArray *)    theRecipients;

变量

变量的命令应尽量做到自描述。除了在 for() 循环语句中，单字母的变量应该避免使用（如 i,j,k 等）。一般循环语句的当前对象的命名前缀包括“ one ”、“ a/an ”。对于简单的单个对象使用“ item ”命名。

良好的风格：

for (i = 0; i < count; i++) {

    oneObject = [ allObjects objectAtIndex: i];

    NSLog (@"oneObject: %@", oneObject);

}

      

NSEnumerator *e = [allObjects objectEnumerator];

id item;

while ( item = [e nextObject])

      NSLog (@"item: %@", item);

指针变量的星号指示符应该紧靠变量，比如 NSString *text, 而不是 NSString* text或 NSString * text 。

尽量的使用属性而非实例变量。除了在初始化方法（ init ， initWithCoder ：等）、 dealloc 方法以及自定义 setter 与 getter 方法中访问属性合成的实例变量，其他的情况使用属性进行访问。

良好的风格：

@interface RNCSection: NSObject

@property (nonatomic) NSString *headline;

@end

不良的风格：

@interface RNCSection : NSObject {

    NSString *headline;

}

当你使用 @synthesize 指令时，编译器会自动为你创建一个下划线 _ 开头的的实例变量，所以不需要同时声明实例变量和属性。

不良的风格：

@interface RNCSection : NSObject {

    NSString *headline;

}

@property (nonatomic) NSString *headline;

@end

良好的风格：

@interface RNCSection: NSObject

@property (nonatomic) NSString *headline;

@end

不要使用 @synthesize 除非是编译器需要。注意在 @protoco 协议中的 @optional可选属性必须被显式地使用 @synthesize 指令合成属性。

缩略词

虽然方法命名不应使用缩略词，然而有些缩略词在过去被反复的使用，所以使用这些缩略词能更好的的表达代码的含义。下表列出了 Cocoa 可接受的缩略词。

缩略词	含义和备注
alloc	分配，拨出
alt	轮流，交替
app	应用程序。比如 NSApp表示全局程序对象。
calc	计算
dealloc	销毁、析构
func	函数
horiz	水平的
info	信息
init	初始化
max	最大的
min	最小的
msg	消息
nib	Interface Builder文档
pboard	黏贴板（仅对常量）
rect	矩形
temp	临时、暂时
vert	垂直的

以下是一些常用的首字母缩略词

ASCII

PDF

XML

HTML

URL

RTF

HTTP

TIFF

JPG

PNG

GIF

LZW

ROM

RGB

CMYK

MIDI

FTP

命名

方法和变量的命令应该尽可能做到自描述。

良好的风格：

UIButton *settingsButton;

不良的风格：

UIButton *setBut;

对于 NSString 、 NSArray 、 NSNumber 或 BOOL 类型，变量的命名一般不需要表明其类型。

良好的风格：

NSString       *accountName;

NSMutableArray *mailboxes;

NSArray        *defaultHeaders;

BOOL             userInputWasUpdated;

不良的风格：

NSString        *accountName String ;

NSMutableArray *mailbox Array ;

NSArray        *defaultHeaders Array ;

BOOL             userInputWasUpdated BOOL ;

如果变量不是以上基本常用类型，则变量的命名就应该反映出自身的类型。但有时仅需要某些类的一个实例的情况下，那么只需要基于类名进行命名。

NSImage               *previewPane Image ; 

NSProgressIndicator  *upload Indicator ; 

NSFontManager        * fontManager ;       // 基于类名命名

大部分情况下， NSArray 或 NSSet 类型的变量只需要使用单词复数形式（比如mailboxes ），不必在命名中包含“ mutable ”。如果复数变量不是 NSArray 或NSSet 类型，则需要指定其类型。

良好的风格：

NSDictionary * keyed AccountNames;

NSDictionary * message Dictionary ;

NSIndexSet   * selectedMailboxes IndexSet ;

由于 Objective-C 不支持名字空间，为了防止出现命名空间的冲突，在类名和常类型变量名前添加一个由三个大写的字母组成的前缀（如 RNC ），对于 Core Data实体名则可以忽略此规则。如果你子类化了标准的 Cocoa 类，将前缀和父类名合并是一个很好的做法。如继承 UITableView 的类可命名为 RNCTableView 。

常类型变量名的书写风格采用驼峰式大小写（第一个单词的首字母小写，其余单词的第一个字母大写。如 firstName 而不是 first_name 或 firstname 。），并使用关联的类名作为其命名前缀，

推荐的做法：

static const NSTimeInterval RNCArticleViewControllerNavigationFadeAnimationDuration = 0.3;

不推荐的做法：

static const NSTimeInterval fadetime = 1.7;

下划线

使用属性的时候，实例变量应该使用 self. 进行访问和设值。局部变量的命令不要包含下划线。实例变量的命名必须使用下划线 _ 作为前缀，这样可以缩小 Xcode自动完成的选项取值范围。

注释

在需要的时候，注释可对代码做必要的解释。更新代码时一定要更新注释，防止对代码造成误解。

使用 javadoc 风格的文档注释语法。注释的第一行是对注释 API 的总结，随后的注释行是对代码更多细节的解释。

良好的风格：

/**

 * The maximum size of a download that is allowed.

 *

 * If a response reports a content length greater than the max * will be cancelled. This is helpful for preventing excessive memory usage.

 * Setting this to zero will allow all downloads regardless of size.

 *

 * @default 150000 bytes

 */

@property (nonatomic) NSUInteger maxContentLength;

init 与 dealloc

dealloc 方法应该被放置在实现方法的顶部，直接在 @synthesize 或 @dynamic 语句之后。 init 方法应该被放置在 dealloc 方法的下面。

init 方法的结构看上去应该像这样：

- (instancetype)init {

    self = [super init]; // or call the designated initalizer

    if (self) {

        // Custom initialization

    }

 

    return self;

}

字面值

对于 NSString ， NSDictionary ， NSArray 和 NSNumber 类，当需要创建这些类的不可变实例时，应该使用这些类的字面值表示形式。使用字面值表示的时候 nil不需要传入 NSArray 和 NSDictionary 中作为字面值。这种语法兼容老的 iOS 版本，因此可以在 iOS5 或者更老的版本中使用它。

良好的风格：

NSArray *names = @[@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul"];

NSDictionary *productManagers = @{@"iPhone" : @"Kate", @"iPad" : @"Kamal", @"Mobile Web" : @"Bill"};

NSNumber *shouldUseLiterals = @YES;

NSNumber *buildingZIPCode = @10018;

不良的风格：

NSArray *names = [NSArray arrayWithObjects:@"Brian", @"Matt", @"Chris", @"Alex", @"Steve", @"Paul", nil];

NSDictionary *productManagers = [NSDictionary dictionaryWithObjectsAndKeys: @"Kate", @"iPhone", @"Kamal", @"iPad", @"Bill", @"Mobile Web", nil];

NSNumber *shouldUseLiterals = [NSNumber numberWithBool:YES];

NSNumber *buildingZIPCode = [NSNumber numberWithInteger:10018];

如非必要，避免使用特定类型的数字（相较于使用 5.3f ，应使用 5.3 ）。

CGRect 函数

相较于使用结构体辅助函数（如 CGRectMake() 函数），优先使用 C99 结构体初始化语法。

  CGRect rect = {.origin.x = 3.0, .origin.y = 12.0, .size.width = 15.0, .size.height = 80.0 };

当访问 CGRect 结构体的 x 、 y 、 width 、 height 成员时，应使用 CGGeometry函数，不直接访问结构体成员。苹果对 CGGeometry 函数的介绍：

All functions described in this reference that take CGRect data structures as inputs implicitly standardize those rectangles before calculating their results. For this reason, your applications should avoid directly reading and writing the data stored in the CGRect data structure. Instead, use the functions described here to manipulate rectangles and to retrieve their characteristics.

良好的风格：

CGRect frame = self.view.frame;

CGFloat x = CGRectGetMinX(frame);

CGFloat y = CGRectGetMinY(frame);

CGFloat width = CGRectGetWidth(frame);

CGFloat height = CGRectGetHeight(frame);

不良的风格：

CGRect frame = self.view.frame;

CGFloat x = frame.origin.x;

CGFloat y = frame.origin.y;

CGFloat width = frame.size.width;

CGFloat height = frame.size.height;

常量

  优先使用常类型变量，而不是内嵌的字符串字面值或数字，因为常类型变量能很容易的复用常用的变量值（如π），同时可以快速地修改值而无需查找替换。常类型变量应该声明为 static 类型，不要使用 #define ，除非常类型变量被作为宏使用。

良好的风格：

static NSString * const RNCAboutViewControllerCompanyName = @"The New York Times Company";

static const CGFloat RNCImageThumbnailHeight = 50.0;

不良的风格：

#define CompanyName @"The New York Times Company"

#define thumbnailHeight 2

枚举类型

当使用 enum 关键字时，推荐使用苹果最新引入的固定基础类型语法，因为这将获得强类型检查与代码完成功能。 SDK 现在包含了一个固定基础类型的宏——NS_ENUM （）。

NS_ENUM 是在 iOS6 中开始引入的，为了支持之前的 iOS 版本，使用简单的内联方法：

#ifndef NS_ENUM

#define NS_ENUM(_type, _name) enum _name : _type _name; enum _name : _type

#endif

良好的风格：

typedef NS_ENUM(NSInteger, RNCAdRequestState) {

    RNCAdRequestStateInactive,

    RNCAdRequestStateLoading

};

私有属性

私有属性应该被声明在实现文件的类扩展中（即匿名的 category ）。不要将私有属性声明在命名的 category （如 RNCPrivate 或 private ），除非是扩展其他类。

良好的风格：

@interface NYTAdvertisement ()

 

@property (nonatomic, strong) GADBannerView *googleAdView;

@property (nonatomic, strong) ADBannerView *iAdView;

@property (nonatomic, strong) UIWebView *adXWebView;

 

@end

图片的命名

图片的命名应该保持一致，以图片的用途描述作为图片文件名。文件名的命名使用驼峰式大小写风格，文件名后可跟随一个自定义的类名或者是自定义的属性名 ( 如果有属性名 ) 、也可以再跟上颜色描述以及 / 或者位置、图片的最终状态。

良好的风格：

RefreshBarButtonItem / RefreshBarButtonItem@2x 和RefreshBarButtonItemSelected / RefreshBarButtonItemSelected@2x

ArticleNavigationBarWhite / ArticleNavigationBarWhite@2x 和ArticleNavigationBarBlackSelected / ArticleNavigationBarBlackSelected@2x.

被用作相似用途的图片应该使用一个图片文件夹进行分开管理。

布尔类型

因为 nil 被解析为了 NO ，所以和 nil 作比较没有任何的必要。不要将变量和 YES直接比较，因为 YES 被定义为 1 而 BOOL 类型是 8 位的 unsigned int ，即 BOOL的值不仅仅是 1 或 0 。

良好的风格：

if (!someObject) {

}

不良的风格：

if (someObject == nil) {

}

对于一个 BOOL 值：两种最佳实践：

if (isAwesome)

if (![someObject boolValue])

不良的风格：

if ([someObject boolValue] == NO)

if (isAwesome == YES) // Never do this.

如果一个 BOOL 类型的属性名是一个形容词，忽略属性名的“ is ”前缀是允许的，但需要为访问器指定约定的方法名，比如：

@property (assign, getter=isEditable) BOOL editable;

单例

应该使用线程安全的模式创建共享的单例实例。

+ (instancetype)sharedInstance {

   static id sharedInstance = nil;

 

   static dispatch_once_t onceToken;

   dispatch_once(&onceToken, ^{

      sharedInstance = [[self alloc] init];

   });

 

   return sharedInstance;

}

附录

Xcode 主题

大部分的开发者都使用 Xcode 默认的字体颜色主题，其实好的主题不仅能提高源代码的辨识度，同时也增添了编码的乐趣。以下是二款 Xcode 字体颜色主题链接：

  https://github.com/vinhnx/Ciapre-Xcode-theme

https://github.com/tursunovic/xcode-themes

代码片段

熟练使用代码片段库可以提高编码的速度。 Xcode4 中，打开一个项目并让右侧编辑区可视，然后点击右侧底部面板的第四个 {} 图标，打开代码片段库，你可以将常用的代码拖入其中。以下是一个最新的开源代码片段库链接：

https://github.com/mattt/Xcode-Snippets

参考文献

[1] 《 NYTimes Objective-C Style Guide 》https://github.com/NYTimes/objective-c-style-guide

[2] 《 Coding Guidelines for Cocoa 》https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/APIAbbreviations.html

[3] 《 iOS-view-frame-builder 》 https://github.com/rsobik/ios-view-frame-builder/commit/0fa2d81762bc21619b1503d34b7d67160f4678f8

[4] 《 Cocoa Style for Objective-C: Part I 》http://cocoadevcentral.com/articles/000082.php

[5] 《 Cocoa Style for Objective-C: Part II 》http://cocoadevcentral.com/articles/000083.php

 [6] 《 objective-c-conventionsI 》 https://github.com/github/objective-c-conventions

      本文由海水的味道翻译整理，转载请注明译者和出处，请勿用于商业用途！

     文章中如有错误或不当之处望不吝指出，谢谢！

     我的邮箱和微博: [email protected], http://weibo.com/xdream86