1.使用空格而不是制表符Tab
不要在工程里使用Tab键,使用空格来进行缩进。在Xcode > Preferences > Text Editing将Tab和自动缩进都设置为4个空格。(Google 的标准是使用两个空格来缩进,但这里还是推荐使用 Xcode 默认的设置。)
2.每一行的最大长度
同样的,在Xcode > Preferences > Text Editing > Page guide at column:中将最大行长设置为80,过长的一行代码将会导致可读性问题。
3.函数的书写
(1).一个典型的Objective-C函数应该是这样的:
- (void)writeVideoFrameWithData:(NSData *)frameData timeStamp (int)timeStamp {
...
}
(2).在-和(void)之间应该有一个空格,第一个大括号{的位置在函数所在行的末尾,同样应该有一个空格。(一般的C语言规范要求是第一个大括号单独占一行,但考虑到 OC较长的函数名和苹果SDK代码的风格,还是将大括号放在行末。)
如果一个函数有特别多的参数或者名称很长,应该将其按照:来对齐分行显示:
-(id)initWithModel:(IPCModle)model
ConnectType:(IPCConnectType)connectType
Resolution:(IPCResolution)resolution
AuthName:(NSString *)authName
Password:(NSString *)password
MAC:(NSString *)mac
AzIp:(NSString *)az_ip
AzDns:(NSString *)az_dns
Token:(NSString *)token
Email:(NSString *)email
Delegate:(id)delegate;
(3).在分行时,如果第一段名称过短,后续名称可以以Tab的长度(4个空格)为单位进行缩进:
- (void)short:(GTMFoo *)theFoo
longKeyword:(NSRect)theRect
evenLongerKeyword:(float)theInterval
error:(NSError **)theError {
...
}
4.函数调用
函数调用的格式和书写差不多,可以按照函数的长短来选择写在一行或者分成多行:
//写在一行
[myObject doFooWith:arg1 name:arg2 error:arg3];
//分行写,按照 ':' 对齐
[myObject doFooWith:arg1
name:arg2
error:arg3];
//第一段名称过短的话后续可以进行缩进
[myObj short:arg1
longKeyword:arg2
evenLongerKeyword:arg3
error:arg4];
以下写法是错误的:
//错误,要么写在一行,要么全部分行
[myObject doFooWith:arg1 name:arg2
error:arg3];
[myObject doFooWith:arg1
name:arg2 error:arg3];
//错误,按照 ':' 来对齐,而不是关键字
[myObject doFooWith:arg1
name:arg2
error:arg3];
5.@public和@private标记符
//@public和@private标记符应该以一个空格来进行缩进:
@interface MyClass : NSObject {
@public
...
@private
...
}
@end
6.协议(Protocols)
在书写协议的时候注意用 <> 括起来的协议和类型名之间是没有空格的,比如 IPCConnectHandler(), 这个规则适用所有书写协议的地方,包括函数声明、类声明、实例变量等等:
@interface MyProtocoledClass : NSObject<NSWindowDelegate> {
@private
id<MyFancyDelegate> _delegate;
}
- (void)setDelegate:(id<MyFancyDelegate>)aDelegate;
@end
7.闭包( Blocks )
Block是创建callback回调时首选的target-selector目标选择器模式,因为它使代码更易于阅读。Block里面的代码块应缩进4个空格。
下面是一些相应的风格规则,取决于block有多长:
如果block能一行写完,不要分行。
如果有分行,右大括号必须与block声明的那一行的第一个字符对齐。
block内的代码必须缩进4个空格。
如果block代码很多,比如,超过20行,建议移到外面用一个本地变量保存。
如果block没有参数,在字符^{之间不要有空格,如果block有参数,字符^(之间不要有空格,但字符){之间有一个空格。
包含内联block的调用可以让其代码段左对齐四空间缩进。这有助于理解包含多个内嵌块的调用。
两个空间内缩进块也可以,但应该只用于保持与项目其他代码风格一致性时。
//较短的block写在一行内
[operation setCompletionBlock:^{ [self onOperationDone]; }];
//分行书写的 block ,内部使用 4 空格缩进
[operation setCompletionBlock:^{
[self.delegate newDataAvailable];
}];
//使用 C 语言 API 调用的 block 遵循同样的书写规则
dispatch_async(_fileIOQueue, ^{
NSString* path = [self sessionFilePath];
if (path) {
// ...
}
});
//较长的 block 关键字可以缩进后在新行书写,注意 block 的右括号 '}' 和调用 block 那行代码的第一个非空字符对齐
[[SessionService sharedService]
loadWindowWithCompletionBlock:^(SessionWindow *window) {
if(window){
[self windowDidLoad:window];
}else{
[self errorLoadingWindow];
}
}];
//较长的block参数列表同样可以缩进后在新行书写
[[SessionService sharedService]
loadWindowWithCompletionBlock:
^(SessionWindow *window) {
if (window) {
[self windowDidLoad:window];
}else{
[self errorLoadingWindow];
}
}];
//庞大的 block 应该单独定义成变量使用
void (^largeBlock)(void) = ^{
// ...
};
[_operationQueue addOperationWithBlock:largeBlock];
//在一个调用中使用多个 block ,注意到他们不是像函数那样通过 ':' 对齐的,而是同时进行了 4 个空格的缩进
[myObject doSomethingWith:arg1
firstBlock:^(Foo *a) {
// ...
}
secondBlock:^(Bar *b) {
// ...
}];
8.容器常量
使用Xcode4.4或更高版本的的项目,鼓励使用容器常量。如果被分成了多行,其内容需两个空白字符缩进。
//如果集合内容只有一行,开始中括号[之后和结束中括号]之前需要一个空格。
NSArray* array = @[ [foo description], @"Another String", [bar description] ];
NSDictionary* dict = @{ NSForegroundColorAttributeName : [NSColor redColor] };
//而不是:
NSArray* array = @[[foo description], [bar description]];
NSDictionary* dict = @{NSForegroundColorAttributeName: [NSColor redColor]};
//如果集合跨越超过一行,左中括号[单独位于声明的那一行,内容缩进两个空格,右括号位于新行并与声明左中括号的行开头对齐。
NSDictionary* dictionary = @{
NSFontAttributeName : [NSFont fontWithName:@"Helvetica-Bold" size:12],
NSForegroundColorAttributeName : fontColor
};
//对于字典常量,冒号前后应该有一个空格(值是否对齐是可选的)
NSDictionary* option1 = @{
NSFontAttributeName : [NSFont fontWithName:@"Helvetica-Bold" size:12],
NSForegroundColorAttributeName : fontColor
};
9.注释
读没有注释代码的痛苦你我都体会过,好的注释不仅能让人轻松读懂你的程序,还能提升代码的逼格。注意注释是为了让别人看懂,而不是仅仅你自己。
(1).文件注释
每一个文件都必须写文件注释,文件注释通常包含
文件所在模块
作者信息
历史版本信息
版权信息
文件包含的内容,作用
一段良好文件注释的例子:
/*******************************************************************************
Copyright (C), 2011-2013, Andrew Min Chang
File name: AMCCommonLib.h
Author: Andrew Chang (Zhang Min)
E-mail: LaplaceZhang@126.com
Description:
This file provide some covenient tool in calling library tools. One can easily include
library headers he wants by declaring the corresponding macros.
I hope this file is not only a header, but also a useful Linux library note.
History:
2012-??-??: On about come date around middle of Year 2012, file created as "commonLib.h"
2012-08-20: Add shared memory library; add message queue.
2012-08-21: Add socket library (local)
2012-08-22: Add math library
2012-08-23: Add socket library (internet)
2012-08-24: Add daemon function
2012-10-10: Change file name as "AMCCommonLib.h"
2012-12-04: Add UDP support in AMC socket library
2013-01-07: Add basic data type such as "sint8_t"
2013-01-18: Add CFG_LIB_STR_NUM.
2013-01-22: Add CFG_LIB_TIMER.
2013-01-22: Remove CFG_LIB_DATA_TYPE because there is already AMCDataTypes.h
Copyright information:
This file was intended to be under GPL protocol. However, I may use this library
in my work as I am an employee. And my company may require me to keep it secret.
Therefore, this file is neither open source nor under GPL control.
********************************************************************************/
文件注释的格式通常不作要求,能清晰易读就可以了,但在整个工程中风格要统一。
(2).代码注释
好的代码应该是 “自解释” (self-documenting)的,但仍然需要详细的注释来说明参数的意义、返回值、功能以及可能的副作用。
方法、函数、类、协议、类别的定义都需要注释,推荐采用 Apple 的标准注释风格,好处是可以在引用的地方 alt+ 点击自动弹出注释,非常方便。
有很多可以自动生成注释格式的插件,推荐使用VVDocumenter。
(3).一些良好的注释:
/**
* Create a new preconnector to replace the old one with given mac address.
* NOTICE: We DO NOT stop the old preconnector, so handle it by yourself.
*
* @param type Connect type the preconnector use.
* @param macAddress Preconnector's mac address.
*/
- (void)refreshConnectorWithConnectType:(IPCConnectType)type Mac:(NSString *)macAddress;
/**
* Stop current preconnecting when application is going to background.
*/
-(void)stopRunning;
/**
* Get the COPY of cloud device with a given mac address.
*
* @param macAddress Mac address of the device.
*
* @return Instance of IPCCloudDevice.
*/
-(IPCCloudDevice *)getCloudDeviceWithMac:(NSString *)macAddress;
// A delegate for NSApplication to handle notifications about app
// launch and shutdown. Owned by the main app controller.
@interface MyAppDelegate : NSObject {
...
}
@end
协议、委托的注释要明确说明其被触发的条件:
/** Delegate - Sent when failed to init connection, like p2p failed. */
-(void)initConnectionDidFailed:(IPCConnectHandler *)handler;
如果在注释中要引用参数名或者方法函数名,使用 || 将参数或者方法括起来以避免歧义:
// Sometimes we need |count| to be less than zero.
// Remember to call |StringWithoutSpaces("foo bar baz")|
定义在头文件里的接口方法、属性必须要有注释!
10.编码风格
每个人都有自己的编码风格,这里总结了一些比较好的 Cocoa 编程风格和注意点。
(1).不要使用 new 方法
尽管很多时候能用new代替alloc init方法,但这可能会导致调试内存时出现不可预料的问题。Cocoa的规范就是使用 alloc init方法,使用new会让一些读者困惑。
(2).Public API 要尽量简洁
共有接口要设计的简洁,满足核心的功能需求就可以了。不要设计很少会被用到,但是参数极其复杂的 API 。如果要定义复杂的方法,使用类别或者类扩展。
(3).#import 和 #include
#import是Cocoa中常用的引用头文件的方式,它能自动防止重复引用文件,什么时候使用 #import ,什么时候使用 #include 呢?
当引用的是一个 Objective-C或者Objective-C++ 的头文件时,使用 #import
当引用的是一个 C 或者 C++ 的头文件时,使用 #include ,这时必须要保证被引用的文件提供了保护域( #define guard )。
例子:
#import
#include
#import "GTMFoo.h"
#include "base/basictypes.h"
为什么不全部使用 #import 呢?主要是为了保证代码在不同平台间共享时不出现问题。
(4).引用框架的根头文件
上面提到过,每一个框架都会有一个和框架同名的头文件,它包含了框架内接口的所有引用,在使用框架的时候,应该直接引用这个根头文件,而不是其它子模块的头文件,即使是你只用到了其中的一小部分,编译器会自动完成优化的。
// 正确,引用根头文件
#import
// 错误,不要单独引用框架内的其它头文件
#import
#import
(5).BOOL 的使用
BOOL在Objective-C中被定义为signed char类型,这意味着一个BOOL类型的变量不仅仅可以表示YES(1)和NO(0) 两个值,所以永远不要将 BOOL 类型变量直接和 YES 比较:
// 错误,无法确定 |great| 的值是否是 YES(1) ,不要将 BOOL 值直接与 YES 比较
BOOL great = [foo isGreat];
if (great == YES)
// ...be great!
// 正确
BOOL great = [foo isGreat];
if (great)
// ...be great!
//同样的,也不要将其它类型的值作为 BOOL 来返回,这种情况下, BOOL 变量只会取值的最后一个字节来赋值,这样很可能会取到 0 ( NO )。但是,一些逻辑操作符比如 &&,||,! 的返回是可以直接赋给 BOOL 的:
// 错误,不要将其它类型转化为 BOOL 返回
- (BOOL)isBold {
return [self fontTraits] & NSFontBoldTrait;
}
- (BOOL)isValid {
return [self stringValue];
}
// 正确
- (BOOL)isBold {
return ([self fontTraits] & NSFontBoldTrait) ? YES : NO;
}
// 正确,逻辑操作符可以直接转化为 BOOL
- (BOOL)isValid {
return [self stringValue] != nil;
}
- (BOOL)isEnabled {
return [self isValid] && [self isBold];
}
另外 BOOL 类型可以和 _Bool,bool 相互转化,但是不能和 Boolean 转化。
(6).使用 ARC
除非想要兼容一些古董级的机器和操作系统,我们没有理由放弃使用 ARC 。在最新版的 Xcode(6.2) 中, ARC 是自动打开的,所以直接使用就好了。
在 init 和 dealloc 中不要用存取方法访问实例变量
当 initdealloc 方法被执行时,类的运行时环境不是处于正常状态的,使用存取方法访问变量可能会导致不可预料的结果,因此应当在这两个方法内直接访问实例变量。
// 正确,直接访问实例变量
- (instancetype)init {
self = [super init];
if (self) {
_bar = [[NSMutableString alloc] init];
}
return self;
}
- (void)dealloc {
[_bar release];
[super dealloc];
}
// 错误,不要通过存取方法访问
- (instancetype)init {
self = [super init];
if (self) {
self.bar = [NSMutableString string];
}
return self;
}
- (void)dealloc {
self.bar = nil;
[super dealloc];
}
按照定义的顺序释放资源
在类或者 Controller 的生命周期结束时,往往需要做一些扫尾工作,比如释放资源,停止线程等,这些扫尾工作的释放顺序应当与它们的初始化或者定义的顺序保持一致。这样做是为了方便调试时寻找错误,也能防止遗漏。
保证 NSString 在赋值时被复制
NSString 非常常用,在它被传递或者赋值时应当保证是以复制( copy )的方式进行的,这样可以防止在不知情的情况下 String 的值被其它对象修改。
- (void)setFoo:(NSString *)aFoo {
_foo = [aFoo copy];
}
(7).使用 NSNumber
//使用带有 @ 符号的语法糖来生成 NSNumber 对象能使代码更简洁:
NSNumber *fortyTwo = @42;
NSNumber *piOverTwo = @(M_PI / 2);
enum {
kMyEnum = 2;
};
NSNumber *myEnum = @(kMyEnum);
//nil 检查
//因为在 Objective-C 中向 nil 对象发送命令是不会抛出异常或者导致崩溃的,只是完全的 “ 什么都不干 ” ,所以,只在程序中使用 nil 来做逻辑上的检查。
//另外,不要使用诸如 nil == Object 或者 Object == nil 的形式来判断。
// 正确,直接判断
if (!objc) {
...
}
// 错误,不要使用 nil == Object 的形式
if (nil == objc) {
...
}
(8).属性的线程安全
定义一个属性时,编译器会自动生成线程安全的存取方法( Atomic ),但这样会大大降低性能,特别是对于那些需要频繁存取的属性来说,是极大的浪费。所以如果定义的属性不需要线程保护,记得手动添加属性关键字 nonatomic 来取消编译器的优化。
点分语法的使用
不要用点分语法来调用方法,只用来访问属性。这样是为了防止代码可读性问题。
// 正确,使用点分语法访问属性
NSString *oldName = myObject.name;
myObject.name = @"Alice";
// 错误,不要用点分语法调用方法
NSArray *array = [NSArray arrayWithObject:@"hello"];
NSUInteger numberOfItems = array.count;
array.release;
Delegate 要使用弱引用
一个类的 Delegate 对象通常还引用着类本身,这样很容易造成引用循环的问题,所以类的 Delegate 属性要设置为弱引用。