Objective-C-Coding-Guidelines-In-Chinese

 

Objective-C-Coding-Guidelines-In-Chinese

Objective-C编码规范，内容来自苹果、谷歌的文档翻译，本身的编码经验和对其它资料的总结。

转载请注明出处。

##概要

Objective-C是一门面向对象的动态编程语言，主要用于编写iOS和Mac应用程序。关于Objective-C的编码规范，苹果和谷歌都已经有很好的总结：

• Apple Coding Guidelines for Cocoa
• Google Objective-C Style Guide

本文主要整合了对上述文档的翻译、做者本身的编程经验和其余的相关资料，为公司总结出一份通用的编码规范。

##代码格式

###使用空格而不是制表符Tab

不要在工程里使用Tab键，使用空格来进行缩进。在Xcode > Preferences > Text Editing将Tab和自动缩进都设置为4个空格。（Google的标准是使用两个空格来缩进，但这里仍是推荐使用Xcode默认的设置。）

###每一行的最大长度

一样的，在Xcode > Preferences > Text Editing > Page guide at column:中将最大行长设置为80，过长的一行代码将会致使可读性问题。

###函数的书写

一个典型的Objective-C函数应该是这样的：

1. - (void)writeVideoFrameWithData:(NSData *)frameData timeStamp:(int)timeStamp {
2. ...
3. }

在-和(void)之间应该有一个空格，第一个大括号{的位置在函数所在行的末尾，一样应该有一个空格。（我司的C语言规范要求是第一个大括号单独占一行，但考虑到OC较长的函数名和苹果SDK代码的风格，仍是将大括号放在行末。）

若是一个函数有特别多的参数或者名称很长，应该将其按照:来对齐分行显示：

1. -(id)initWithModel:(IPCModle)model
2. ConnectType:(IPCConnectType)connectType
3. Resolution:(IPCResolution)resolution
4. AuthName:(NSString *)authName
5. Password:(NSString *)password
6. MAC:(NSString *)mac
7. AzIp:(NSString *)az_ip
8. AzDns:(NSString *)az_dns
9. Token:(NSString *)token
10. Email:(NSString *)email
11. Delegate:(id<IPCConnectHandlerDelegate>)delegate;

在分行时，若是第一段名称太短，后续名称能够以Tab的长度（4个空格）为单位进行缩进：

1. - (void)short:(GTMFoo *)theFoo
2. longKeyword:(NSRect)theRect
3. evenLongerKeyword:(float)theInterval
4. error:(NSError **)theError {
5. ...
6. }

###函数调用

函数调用的格式和书写差很少，能够按照函数的长短来选择写在一行或者分红多行：

1. //写在一行
2. [myObject doFooWith:arg1 name:arg2 error:arg3];
4. //分行写，按照':'对齐
5. [myObject doFooWith:arg1
6. name:arg2
7. error:arg3];
9. //第一段名称太短的话后续能够进行缩进
10. [myObj short:arg1
11. longKeyword:arg2
12. evenLongerKeyword:arg3
13. error:arg4];

如下写法是错误的：

1. //错误，要么写在一行，要么所有分行
2. [myObject doFooWith:arg1 name:arg2
3. error:arg3];
4. [myObject doFooWith:arg1
5. name:arg2 error:arg3];
7. //错误，按照':'来对齐，而不是关键字
8. [myObject doFooWith:arg1
9. name:arg2
10. error:arg3];

###@public和@private标记符

@public和@private标记符应该以一个空格来进行缩进：

1. @interface MyClass : NSObject {
2. @public
3. ...
4. @private
5. ...
6. }
7. @end

###协议（Protocols）

在书写协议的时候注意用<>括起来的协议和类型名之间是没有空格的，好比IPCConnectHandler()<IPCPreconnectorDelegate>,这个规则适用全部书写协议的地方，包括函数声明、类声明、实例变量等等：

1. @interface MyProtocoledClass : NSObject<NSWindowDelegate> {
2. @private
3. id<MyFancyDelegate> _delegate;
4. }
6. - (void)setDelegate:(id<MyFancyDelegate>)aDelegate;
7. @end

###闭包（Blocks）

根据block的长度，有不一样的书写规则：

• 较短的block能够写在一行内。
• 若是分行显示的话，block的右括号}应该和调用block那行代码的第一个非空字符对齐。
• block内的代码采用4个空格的缩进。
• 若是block过于庞大，应该单独声明成一个变量来使用。
• ^和(之间，^和{之间都没有空格，参数列表的右括号)和{之间有一个空格。

1. //较短的block写在一行内
2. [operation setCompletionBlock:^{ [self onOperationDone]; }];
4. //分行书写的block，内部使用4空格缩进
5. [operation setCompletionBlock:^{
6. [self.delegate newDataAvailable];
7. }];
9. //使用C语言API调用的block遵循一样的书写规则
10. dispatch_async(_fileIOQueue, ^{
11. NSString* path = [self sessionFilePath];
12. if (path) {
13. // ...
14. }
15. });
17. //较长的block关键字能够缩进后在新行书写，注意block的右括号'}'和调用block那行代码的第一个非空字符对齐
18. [[SessionService sharedService]
19. loadWindowWithCompletionBlock:^(SessionWindow *window) {
20. if (window) {
21. [self windowDidLoad:window];
22. } else {
23. [self errorLoadingWindow];
24. }
25. }];
27. //较长的block参数列表一样能够缩进后在新行书写
28. [[SessionService sharedService]
29. loadWindowWithCompletionBlock:
30. ^(SessionWindow *window) {
31. if (window) {
32. [self windowDidLoad:window];
33. } else {
34. [self errorLoadingWindow];
35. }
36. }];
38. //庞大的block应该单独定义成变量使用
39. void (^largeBlock)(void) = ^{
40. // ...
41. };
42. [_operationQueue addOperationWithBlock:largeBlock];
44. //在一个调用中使用多个block，注意到他们不是像函数那样经过':'对齐的，而是同时进行了4个空格的缩进
45. [myObject doSomethingWith:arg1
46. firstBlock:^(Foo *a) {
47. // ...
48. }
49. secondBlock:^(Bar *b) {
50. // ...
51. }];

###数据结构的语法糖

应该使用可读性更好的语法糖来构造NSArray，NSDictionary等数据结构，避免使用冗长的alloc,init方法。

若是构造代码写在一行，须要在括号两端留有一个空格，使得被构造的元素于与构造语法区分开来：

1. //正确，在语法糖的"[]"或者"{}"两端留有空格
2. NSArray *array = @[ [foo description], @"Another String", [bar description] ];
3. NSDictionary *dict = @{ NSForegroundColorAttributeName : [NSColor redColor] };
5. //不正确，不留有空格下降了可读性
6. NSArray* array = @[[foo description], [bar description]];
7. NSDictionary* dict = @{NSForegroundColorAttributeName: [NSColor redColor]};

若是构造代码不写在一行内，构造元素须要使用两个空格来进行缩进，右括号]或者}写在新的一行，而且与调用语法糖那行代码的第一个非空字符对齐：

1. NSArray *array = @[
2. @"This",
3. @"is",
4. @"an",
5. @"array"
6. ];
8. NSDictionary *dictionary = @{
9. NSFontAttributeName : [NSFont fontWithName:@"Helvetica-Bold" size:12],
10. NSForegroundColorAttributeName : fontColor
11. };

构造字典时，字典的Key和Value与中间的冒号:都要留有一个空格，多行书写时，也能够将Value对齐：

1. //正确，冒号':'先后留有一个空格
2. NSDictionary *option1 = @{
3. NSFontAttributeName : [NSFont fontWithName:@"Helvetica-Bold" size:12],
4. NSForegroundColorAttributeName : fontColor
5. };
7. //正确，按照Value来对齐
8. NSDictionary *option2 = @{
9. NSFontAttributeName : [NSFont fontWithName:@"Arial" size:12],
10. NSForegroundColorAttributeName : fontColor
11. };
13. //错误，冒号前应该有一个空格
14. NSDictionary *wrong = @{
15. AKey: @"b",
16. BLongerKey: @"c",
17. };
19. //错误，每个元素要么单独成为一行，要么所有写在一行内
20. NSDictionary *alsoWrong= @{ AKey : @"a",
21. BLongerKey : @"b" };
23. //错误，在冒号前只能有一个空格，冒号后才能够考虑按照Value对齐
24. NSDictionary *stillWrong = @{
25. AKey : @"b",
26. BLongerKey : @"c",
27. };

##命名规范

###基本原则

####清晰

命名应该尽量的清晰和简洁，但在Objective-C中，清晰比简洁更重要。因为Xcode强大的自动补全功能，咱们没必要担忧名称过长的问题。

1. //清晰
2. insertObject:atIndex:
4. //不清晰，insert的对象类型和at的位置属性没有说明
5. insert:at:
7. //清晰
8. removeObjectAtIndex:
10. //不清晰，remove的对象类型没有说明，参数的做用没有说明
11. remove:

不要使用单词的简写，拼写出完整的单词：

1. //清晰
2. destinationSelection
3. setBackgroundColor:
5. //不清晰，不要使用简写
6. destSel
7. setBkgdColor:

然而，有部分单词简写在Objective-C编码过程当中是很是经常使用的，以致于成为了一种规范，这些简写能够在代码中直接使用，下面列举了部分：

1. alloc == Allocate max == Maximum
2. alt == Alternate min == Minimum
3. app == Application msg == Message
4. calc == Calculate nib == Interface Builder archive
5. dealloc == Deallocate pboard == Pasteboard
6. func == Function rect == Rectangle
7. horiz == Horizontal Rep == Representation (used in class name such as NSBitmapImageRep).
8. info == Information temp == Temporary
9. init == Initialize vert == Vertical
10. int == Integer

命名方法或者函数时要避免歧义

1. //有歧义，是返回sendPort仍是send一个Port？
2. sendPort
4. //有歧义，是返回一个名字属性的值仍是display一个name的动做？
5. displayName

####一致性

整个工程的命名风格要保持一致性，最好和苹果SDK的代码保持统一。不一样类中完成类似功能的方法应该叫同样的名字，好比咱们老是用count来返回集合的个数，不能在A类中使用count而在B类中使用getNumber。

###使用前缀

若是代码须要打包成Framework给别的工程使用，或者工程项目很是庞大，须要拆分红不一样的模块，使用命名前缀是很是有用的。

• 前缀由大写的字母缩写组成，好比Cocoa中NS前缀表明Founation框架中的类，IB则表明Interface Builder框架。

• 能够在为类、协议、函数、常量以及typedef宏命名的时候使用前缀，但注意不要为成员变量或者方法使用前缀，由于他们自己就包含在类的命名空间内。

• 命名前缀的时候不要和苹果SDK框架冲突。

###命名类和协议（Class&Protocol）

类名以大写字母开头，应该包含一个名词来表示它表明的对象类型，同时能够加上必要的前缀，好比NSString, NSDate, NSScanner, NSApplication等等。

而协议名称应该清晰地表示它所执行的行为，并且要和类名区别开来，因此一般使用ing词尾来命名一个协议，好比NSCopying,NSLocking。

有些协议自己包含了不少不相关的功能，主要用来为某一特定类服务，这时候能够直接用类名来命名这个协议，好比NSObject协议，它包含了id对象在生存周期内的一系列方法。

###命名头文件（Headers）

源码的头文件名应该清晰地暗示它的功能和包含的内容：

• 若是头文件内只定义了单个类或者协议，直接用类名或者协议名来命名头文件，好比NSLocale.h定义了NSLocale类。

• 若是头文件内定义了一系列的类、协议、类别，使用其中最主要的类名来命名头文件，好比NSString.h定义了NSString和NSMutableString。

• 每个Framework都应该有一个和框架同名的头文件，包含了框架中全部公共类头文件的引用，好比Foundation.h

• Framework中有时候会实如今别的框架中类的类别扩展，这样的文件一般使用被扩展的框架名+Additions的方式来命名，好比NSBundleAdditions.h。

###命名方法（Methods）

Objective-C的方法名一般都比较长，这是为了让程序有更好地可读性，按苹果的说法“好的方法名应当能够以一个句子的形式朗读出来”。

方法通常以小写字母打头，每个后续的单词首字母大写，方法名中不该该有标点符号（包括下划线），有两个例外：

• 能够用一些通用的大写字母缩写打头方法，好比PDF,TIFF等。
• 能够用带下划线的前缀来命名私有方法或者类别中的方法。

若是方法表示让对象执行一个动做，使用动词打头来命名，注意不要使用do，does这种多余的关键字，动词自己的暗示就足够了：

1. //动词打头的方法表示让对象执行一个动做
2. - (void)invokeWithTarget:(id)target;
3. - (void)selectTabViewItem:(NSTabViewItem *)tabViewItem;

若是方法是为了获取对象的一个属性值，直接用属性名称来命名这个方法，注意不要添加get或者其余的动词前缀：

1. //正确，使用属性名来命名方法
2. - (NSSize)cellSize;
4. //错误，添加了多余的动词前缀
5. - (NSSize)calcCellSize;
6. - (NSSize)getCellSize;

对于有多个参数的方法，务必在每个参数前都添加关键词，关键词应当清晰说明参数的做用：

1. //正确，保证每一个参数都有关键词修饰
2. - (void)sendAction:(SEL)aSelector toObject:(id)anObject forAllCells:(BOOL)flag;
4. //错误，遗漏关键词
5. - (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;
7. //正确
8. - (id)viewWithTag:(NSInteger)aTag;
10. //错误，关键词的做用不清晰
11. - (id)taggedView:(int)aTag;

不要用and来链接两个参数，一般and用来表示方法执行了两个相对独立的操做（从设计上来讲，这时候应该拆分红两个独立的方法）：

1. //错误，不要使用"and"来链接参数
2. - (int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes;
4. //正确，使用"and"来表示两个相对独立的操做
5. - (BOOL)openFile:(NSString *)fullPath withApplication:(NSString *)appName andDeactivate:(BOOL)flag;

方法的参数命名也有一些须要注意的地方:

• 和方法名相似，参数的第一个字母小写，后面的每个单词首字母大写
• 不要再方法名中使用相似pointer,ptr这样的字眼去表示指针，参数自己的类型足以说明
• 不要使用只有一两个字母的参数名
• 不要使用简写，拼出完整的单词

下面列举了一些经常使用参数名：

1. ...action:(SEL)aSelector
2. ...alignment:(int)mode
3. ...atIndex:(int)index
4. ...content:(NSRect)aRect
5. ...doubleValue:(double)aDouble
6. ...floatValue:(float)aFloat
7. ...font:(NSFont *)fontObj
8. ...frame:(NSRect)frameRect
9. ...intValue:(int)anInt
10. ...keyEquivalent:(NSString *)charCode
11. ...length:(int)numBytes
12. ...point:(NSPoint)aPoint
13. ...stringValue:(NSString *)aString
14. ...tag:(int)anInt
15. ...target:(id)anObject
16. ...title:(NSString *)aString

###存取方法（Accessor Methods）

存取方法是指用来获取和设置类属性值的方法，属性的不一样类型，对应着不一样的存取方法规范：

1. //属性是一个名词时的存取方法范式
2. - (type)noun;
3. - (void)setNoun:(type)aNoun;
4. //栗子
5. - (NSString *)title;
6. - (void)setTitle:(NSString *)aTitle;
8. //属性是一个形容词时存取方法的范式
9. - (BOOL)isAdjective;
10. - (void)setAdjective:(BOOL)flag;
11. //栗子
12. - (BOOL)isEditable;
13. - (void)setEditable:(BOOL)flag;
15. //属性是一个动词时存取方法的范式
16. - (BOOL)verbObject;
17. - (void)setVerbObject:(BOOL)flag;
18. //栗子
19. - (BOOL)showsAlpha;
20. - (void)setShowsAlpha:(BOOL)flag;

命名存取方法时不要将动词转化为被动形式来使用：

1. //正确
2. - (void)setAcceptsGlyphInfo:(BOOL)flag;
3. - (BOOL)acceptsGlyphInfo;
5. //错误，不要使用动词的被动形式
6. - (void)setGlyphInfoAccepted:(BOOL)flag;
7. - (BOOL)glyphInfoAccepted;

可使用can,should,will等词来协助表达存取方法的意思，但不要使用do,和does：

1. //正确
2. - (void)setCanHide:(BOOL)flag;
3. - (BOOL)canHide;
4. - (void)setShouldCloseDocument:(BOOL)flag;
5. - (BOOL)shouldCloseDocument;
7. //错误，不要使用"do"或者"does"
8. - (void)setDoesAcceptGlyphInfo:(BOOL)flag;
9. - (BOOL)doesAcceptGlyphInfo;

为何Objective-C中不适用get前缀来表示属性获取方法？由于get在Objective-C中一般只用来表示从函数指针返回值的函数：

1. //三个参数都是做为函数的返回值来使用的，这样的函数名可使用"get"前缀
2. - (void)getLineDash:(float *)pattern count:(int *)count phase:(float *)phase;

###命名委托（Delegate）

当特定的事件发生时，对象会触发它注册的委托方法。委托是Objective-C中经常使用的传递消息的方式。委托有它固定的命名范式。

一个委托方法的第一个参数是触发它的对象，第一个关键词是触发对象的类名，除非委托方法只有一个名为sender的参数：

1. //第一个关键词为触发委托的类名
2. - (BOOL)tableView:(NSTableView *)tableView shouldSelectRow:(int)row;
3. - (BOOL)application:(NSApplication *)sender openFile:(NSString *)filename;
5. //当只有一个"sender"参数时能够省略类名
6. - (BOOL)applicationOpenUntitledFile:(NSApplication *)sender;

根据委托方法触发的时机和目的，使用should,will,did等关键词

1. - (void)browserDidScroll:(NSBrowser *)sender;
3. - (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window;、
5. - (BOOL)windowShouldClose:(id)sender;

###集合操做类方法（Collection Methods）

有些对象管理着一系列其它对象或者元素的集合，须要使用相似“增删查改”的方法来对集合进行操做，这些方法的命名范式通常为：

1. //集合操做范式
2. - (void)addElement:(elementType)anObj;
3. - (void)removeElement:(elementType)anObj;
4. - (NSArray *)elements;
6. //栗子
7. - (void)addLayoutManager:(NSLayoutManager *)obj;
8. - (void)removeLayoutManager:(NSLayoutManager *)obj;
9. - (NSArray *)layoutManagers;

注意，若是返回的集合是无序的，使用NSSet来代替NSArray。若是须要将元素插入到特定的位置，使用相似于这样的命名：

1. - (void)insertLayoutManager:(NSLayoutManager *)obj atIndex:(int)index;
2. - (void)removeLayoutManagerAtIndex:(int)index;

若是管理的集合元素中有指向管理对象的指针，要设置成weak类型以防止引用循环。

下面是SDK中NSWindow类的集合操做方法：

1. - (void)addChildWindow:(NSWindow *)childWin ordered:(NSWindowOrderingMode)place;
2. - (void)removeChildWindow:(NSWindow *)childWin;
3. - (NSArray *)childWindows;
4. - (NSWindow *)parentWindow;
5. - (void)setParentWindow:(NSWindow *)window;

###命名函数（Functions）

在不少场合仍然须要用到函数，好比说若是一个对象是一个单例，那么应该使用函数来代替类方法执行相关操做。

函数的命名和方法有一些不一样，主要是：

• 函数名称通常带有缩写前缀，表示方法所在的框架。
• 前缀后的单词以“驼峰”表示法显示，第一个单词首字母大写。

函数名的第一个单词一般是一个动词，表示方法执行的操做：

1. NSHighlightRect
2. NSDeallocateObject

若是函数返回其参数的某个属性，省略动词：

1. unsigned int NSEventMaskFromType(NSEventType type)
2. float NSHeight(NSRect aRect)

若是函数经过指针参数来返回值，须要在函数名中使用Get：

1. const char *NSGetSizeAndAlignment(const char *typePtr, unsigned int *sizep, unsigned int *alignp)

函数的返回类型是BOOL时的命名：

1. BOOL NSDecimalIsNotANumber(const NSDecimal *decimal)

###命名属性和实例变量（Properties&Instance Variables）

属性和对象的存取方法相关联，属性的第一个字母小写，后续单词首字母大写，没必要添加前缀。属性按功能命名成名词或者动词：

1. //名词属性
2. @property (strong) NSString *title;
4. //动词属性
5. @property (assign) BOOL showsAlpha;

属性也能够命名成形容词，这时候一般会指定一个带有is前缀的get方法来提升可读性：

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

命名实例变量，在变量名前加上_前缀（有些有历史的代码会将_放在后面），其它和命名属性同样：

1. @implementation MyClass {
2. BOOL _showsTitle;
3. }

通常来讲，类须要对使用者隐藏数据存储的细节，因此不要将实例方法定义成公共可访问的接口，可使用@private，@protected前缀。

按苹果的说法，不建议在除了init和dealloc方法之外的地方直接访问实例变量，但不少人认为直接访问会让代码更加清晰可读，只在须要计算或者执行操做的时候才使用存取方法访问，我就是这种习惯，因此这里不做要求。

###命名常量（Constants）

若是要定义一组相关的常量，尽可能使用枚举类型（enumerations），枚举类型的命名规则和函数的命名规则相同。
建议使用 NS_ENUM 和 NS_OPTIONS 宏来定义枚举类型，参见官方的 Adopting Modern Objective-C 一文：

1. //定义一个枚举
2. typedef NS_ENUM(NSInteger, NSMatrixMode) {
3. NSRadioModeMatrix,
4. NSHighlightModeMatrix,
5. NSListModeMatrix,
6. NSTrackModeMatrix
7. };

定义bit map：

1. typedef NS_OPTIONS(NSUInteger, NSWindowMask) {
2. NSBorderlessWindowMask = 0,
3. NSTitledWindowMask = 1 << 0,
4. NSClosableWindowMask = 1 << 1,
5. NSMiniaturizableWindowMask = 1 << 2,
6. NSResizableWindowMask = 1 << 3
7. };

使用const定义浮点型或者单个的整数型常量，若是要定义一组相关的整数常量，应该优先使用枚举。常量的命名规范和函数相同：

1. const float NSLightGray;

不要使用#define宏来定义常量，若是是整型常量，尽可能使用枚举，浮点型常量，使用const定义。#define一般用来给编译器决定是否编译某块代码，好比经常使用的：

1. #ifdef DEBUG

注意到通常由编译器定义的宏会在先后都有一个__，好比__MACH__。

###命名通知（Notifications）

通知经常使用于在模块间传递消息，因此通知要尽量地表示出发生的事件，通知的命名范式是：

1. [触发通知的类名] + [Did | Will] + [动做] + Notification

栗子：

1. NSApplicationDidBecomeActiveNotification
2. NSWindowDidMiniaturizeNotification
3. NSTextViewDidChangeSelectionNotification
4. NSColorPanelColorDidChangeNotification

##注释

读没有注释代码的痛苦你我都体会过，好的注释不只能让人轻松读懂你的程序，还能提高代码的逼格。注意注释是为了让别人看懂，而不是仅仅你本身。

###文件注释

每个文件都必须写文件注释，文件注释一般包含

• 文件所在模块
• 做者信息
• 历史版本信息
• 版权信息
• 文件包含的内容，做用

一段良好文件注释的栗子：

1. /*******************************************************************************
2. Copyright (C), 2011-2013, Andrew Min Chang
4. File name: AMCCommonLib.h
5. Author: Andrew Chang (Zhang Min)
6. E-mail: LaplaceZhang@126.com
8. Description:
9. This file provide some covenient tool in calling library tools. One can easily include
10. library headers he wants by declaring the corresponding macros.
11. I hope this file is not only a header, but also a useful Linux library note.
13. History:
14. 2012-??-??: On about come date around middle of Year 2012, file created as "commonLib.h"
15. 2012-08-20: Add shared memory library; add message queue.
16. 2012-08-21: Add socket library (local)
17. 2012-08-22: Add math library
18. 2012-08-23: Add socket library (internet)
19. 2012-08-24: Add daemon function
20. 2012-10-10: Change file name as "AMCCommonLib.h"
21. 2012-12-04: Add UDP support in AMC socket library
22. 2013-01-07: Add basic data type such as "sint8_t"
23. 2013-01-18: Add CFG_LIB_STR_NUM.
24. 2013-01-22: Add CFG_LIB_TIMER.
25. 2013-01-22: Remove CFG_LIB_DATA_TYPE because there is already AMCDataTypes.h
27. Copyright information:
28. This file was intended to be under GPL protocol. However, I may use this library
29. in my work as I am an employee. And my company may require me to keep it secret.
30. Therefore, this file is neither open source nor under GPL control.
32. ********************************************************************************/

文件注释的格式一般不做要求，能清晰易读就能够了，但在整个工程中风格要统一。

###代码注释

好的代码应该是“自解释”（self-documenting）的，但仍然须要详细的注释来讲明参数的意义、返回值、功能以及可能的反作用。

方法、函数、类、协议、类别的定义都须要注释，推荐采用Apple的标准注释风格，好处是能够在引用的地方alt+点击自动弹出注释，很是方便。

有不少能够自动生成注释格式的插件，推荐使用VVDocumenter：

一些良好的注释：

1. /**
2. * Create a new preconnector to replace the old one with given mac address.
3. * NOTICE: We DO NOT stop the old preconnector, so handle it by yourself.
4. *
5. * @param type Connect type the preconnector use.
6. * @param macAddress Preconnector's mac address.
7. */
8. - (void)refreshConnectorWithConnectType:(IPCConnectType)type Mac:(NSString *)macAddress;
10. /**
11. * Stop current preconnecting when application is going to background.
12. */
13. -(void)stopRunning;
15. /**
16. * Get the COPY of cloud device with a given mac address.
17. *
18. * @param macAddress Mac address of the device.
19. *
20. * @return Instance of IPCCloudDevice.
21. */
22. -(IPCCloudDevice *)getCloudDeviceWithMac:(NSString *)macAddress;
24. // A delegate for NSApplication to handle notifications about app
25. // launch and shutdown. Owned by the main app controller.
26. @interface MyAppDelegate : NSObject {
27. ...
28. }
29. @end

协议、委托的注释要明确说明其被触发的条件：

1. /** Delegate - Sent when failed to init connection, like p2p failed. */
2. -(void)initConnectionDidFailed:(IPCConnectHandler *)handler;

若是在注释中要引用参数名或者方法函数名，使用||将参数或者方法括起来以免歧义：

1. // Sometimes we need |count| to be less than zero.
3. // Remember to call |StringWithoutSpaces("foo bar baz")|

定义在头文件里的接口方法、属性必需要有注释！

##编码风格

每一个人都有本身的编码风格，这里总结了一些比较好的Cocoa编程风格和注意点。

###不要使用new方法

尽管不少时候能用new代替alloc init方法，但这可能会致使调试内存时出现不可预料的问题。Cocoa的规范就是使用alloc init方法，使用new会让一些读者困惑。

###Public API要尽可能简洁

共有接口要设计的简洁，知足核心的功能需求就能够了。不要设计不多会被用到，可是参数极其复杂的API。若是要定义复杂的方法，使用类别或者类扩展。

####import和#include

#import是Cocoa中经常使用的引用头文件的方式，它能自动防止重复引用文件，何时使用#import，何时使用#include呢？

• 当引用的是一个Objective-C或者Objective-C++的头文件时，使用#import
• 当引用的是一个C或者C++的头文件时，使用#include，这时必需要保证被引用的文件提供了保护域（#define guard）。

栗子：

1. #import <Cocoa/Cocoa.h>
2. #include <CoreFoundation/CoreFoundation.h>
3. #import "GTMFoo.h"
4. #include "base/basictypes.h"

为何不所有使用#import呢？主要是为了保证代码在不一样平台间共享时不出现问题。

###引用框架的根头文件

上面提到过，每个框架都会有一个和框架同名的头文件，它包含了框架内接口的全部引用，在使用框架的时候，应该直接引用这个根头文件，而不是其它子模块的头文件，即便是你只用到了其中的一小部分，编译器会自动完成优化的。

1. //正确，引用根头文件
2. #import <Foundation/Foundation.h>
4. //错误，不要单独引用框架内的其它头文件
5. #import <Foundation/NSArray.h>
6. #import <Foundation/NSString.h>

###BOOL的使用

BOOL在Objective-C中被定义为signed char类型，这意味着一个BOOL类型的变量不只仅能够表示YES(1)和NO(0)两个值，因此永远不要将BOOL类型变量直接和YES比较：

1. //错误，没法肯定|great|的值是不是YES(1)，不要将BOOL值直接与YES比较
2. BOOL great = [foo isGreat];
3. if (great == YES)
4. // ...be great!
6. //正确
7. BOOL great = [foo isGreat];
8. if (great)
9. // ...be great!

一样的，也不要将其它类型的值做为BOOL来返回，这种状况下，BOOL变量只会取值的最后一个字节来赋值，这样极可能会取到0（NO）。可是，一些逻辑操做符好比&&,||,!的返回是能够直接赋给BOOL的：

1. //错误，不要将其它类型转化为BOOL返回
2. - (BOOL)isBold {
3. return [self fontTraits] & NSFontBoldTrait;
4. }
5. - (BOOL)isValid {
6. return [self stringValue];
7. }
9. //正确
10. - (BOOL)isBold {
11. return ([self fontTraits] & NSFontBoldTrait) ? YES : NO;
12. }
14. //正确，逻辑操做符能够直接转化为BOOL
15. - (BOOL)isValid {
16. return [self stringValue] != nil;
17. }
18. - (BOOL)isEnabled {
19. return [self isValid] && [self isBold];
20. }

另外BOOL类型能够和_Bool,bool相互转化，可是不能和Boolean转化。

###使用ARC

除非想要兼容一些古董级的机器和操做系统，咱们没有理由放弃使用ARC。在最新版的Xcode(6.2)中，ARC是自动打开的，因此直接使用就行了。

###在init和dealloc中不要用存取方法访问实例变量

当init``dealloc方法被执行时，类的运行时环境不是处于正常状态的，使用存取方法访问变量可能会致使不可预料的结果，所以应当在这两个方法内直接访问实例变量。

1. //正确，直接访问实例变量
2. - (instancetype)init {
3. self = [super init];
4. if (self) {
5. _bar = [[NSMutableString alloc] init];
6. }
7. return self;
8. }
9. - (void)dealloc {
10. [_bar release];
11. [super dealloc];
12. }
14. //错误，不要经过存取方法访问
15. - (instancetype)init {
16. self = [super init];
17. if (self) {
18. self.bar = [NSMutableString string];
19. }
20. return self;
21. }
22. - (void)dealloc {
23. self.bar = nil;
24. [super dealloc];
25. }

###按照定义的顺序释放资源

在类或者Controller的生命周期结束时，每每须要作一些扫尾工做，好比释放资源，中止线程等，这些扫尾工做的释放顺序应当与它们的初始化或者定义的顺序保持一致。这样作是为了方便调试时寻找错误，也能防止遗漏。

###保证NSString在赋值时被复制

NSString很是经常使用，在它被传递或者赋值时应当保证是以复制（copy）的方式进行的，这样能够防止在不知情的状况下String的值被其它对象修改。

1. - (void)setFoo:(NSString *)aFoo {
2. _foo = [aFoo copy];
3. }

###使用NSNumber的语法糖

使用带有@符号的语法糖来生成NSNumber对象能使代码更简洁：

1. NSNumber *fortyTwo = @42;
2. NSNumber *piOverTwo = @(M_PI / 2);
3. enum {
4. kMyEnum = 2;
5. };
6. NSNumber *myEnum = @(kMyEnum);

###nil检查

由于在Objective-C中向nil对象发送命令是不会抛出异常或者致使崩溃的，只是彻底的“什么都不干”，因此，只在程序中使用nil来作逻辑上的检查。

另外，不要使用诸如nil == Object或者Object == nil的形式来判断。

1. //正确，直接判断
2. if (!objc) {
3. ...
4. }
6. //错误，不要使用nil == Object的形式
7. if (nil == objc) {
8. ...
9. }

###属性的线程安全

定义一个属性时，编译器会自动生成线程安全的存取方法（Atomic），但这样会大大下降性能，特别是对于那些须要频繁存取的属性来讲，是极大的浪费。因此若是定义的属性不须要线程保护，记得手动添加属性关键字nonatomic来取消编译器的优化。

###点分语法的使用

不要用点分语法来调用方法，只用来访问属性。这样是为了防止代码可读性问题。

1. //正确，使用点分语法访问属性
2. NSString *oldName = myObject.name;
3. myObject.name = @"Alice";
5. //错误，不要用点分语法调用方法
6. NSArray *array = [NSArray arrayWithObject:@"hello"];
7. NSUInteger numberOfItems = array.count;
8. array.release;

###Delegate要使用弱引用

一个类的Delegate对象一般还引用着类自己，这样很容易形成引用循环的问题，因此类的Delegate属性要设置为弱引用。

1. /** delegate */
2. @property (nonatomic, weak) id <IPCConnectHandlerDelegate> delegate;