移动端iOS开发规范文档
序言
- 根据网上的一些OC编码规范整理归纳而成，为了利于项目维护以及规范开发，促进成员之间
Code Review的效率
函数的书写
- 方法长度建议不超过80行，如果方法太长可以考虑抽取其中一部分
- 方法（-、+）和返回值前面的左括号间隔一个空格，方法参数直接间隔一个空格。每个方法结束后需间隔一行来书写新方法
- (void)applicationDidEnterBackground:(UIApplication *)application
- (void)applicationWillResignActive:(UIApplication *)application
- 如果一个函数有特别多的参数或者名称特别长，将其按照：来对齐分行显示
-(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<IPCConnectHandlerDelegate>)delegate;
函数的调用
函数调用的格式和书写的差不多，可以按照函数的长短选择写在一行或者分成多行
//写在一行
[myObject doFooWith:arg1 name:arg2 error:arg3];
//分行写，按照 : 对齐
[myObject doFooWith:arg1
name:arg2
error:arg3];
//第一段名称过短的话后续可以进行缩进
[myObj short:arg1
longKeyword:arg2
evenLongerKeyword:arg3
error:arg4];
闭包
-
block的右括号"}"应该和调用block那行代码的第一个非空字符对齐 -
block内的代码采用一个tab(四个空格的距离)的缩进 - 如果
block过于庞大，应该单独声明一个变量来使用
//分行书写的block,内部使用一个tab的缩进
[operation setCompletionBlock:^{
[self.delegate newDataAvailable];
}];
//使用C语言API调用的block遵循同样的书写规则
dispatch_async(_fileIOQueue, ^{
NSString* path = [self sessionFilePath];
if (path) {
// ...
}
});
//庞大的block应该单独定义成变量使用
void (^largeBlock)(void) = ^{
// ...
};
[_operationQueue addOperationWithBlock:largeBlock];
//在一个调用中使用多个block,通过进行一个tab缩进
[myObject doSomethingWith:arg1
firstBlock:^(Foo *a) {
// ...
}
secondBlock:^(Bar *b) {
// ...
}
];
命名规范
项目命名
·项目名都遵循大驼峰命名。例如：AoRiseProject
Bundle Identifier 命名
·Bundle Identifier：采用反域名命名规范，全部采用小写字母，以域名后缀+公司顶级域名+应用名形式命名，例如：com.rogrand.dianbangbang
类名
类的命名都遵循大驼峰命名。一般是：前缀 + 功能 + 类型。例如：CPX + Login + ViewController,在实际开发中，一般都会给工程中所有的类加上属于本工程的前缀。
常用控件类命名类型对照表（下表中前缀为：CPX，如果用到下表中没有列举出来，请去掉UI首字母，遵循实际规则即可。）
| 控件名 | 类型 | 示例 |
|---|---|---|
| UIViewController | ViewController | CPXBaseViewController |
| UView | View | CPXBaseView |
| UITableView | TableView | CPXOrderTableView |
| UITableViewCell | Cell | CPXOrderListCell |
| UIButton | Button | CPXSuccessButton |
| UILabel | Label | CPXSuccessLabel |
| UIImageView | ImgView | CPXGoodsImgView |
| UITextField | TextField | CPXNameTextField |
| UITextView | TextView | CPXSuggestTextView |
常量
·宏：小写k+大驼峰 即为：#define kUserAgeKey @“ageKey”
·全局常量：工程前+缀全大写，下划线隔开 即为：extern const NSString MW_USER_AGE_KEY
清晰
- 命名应该尽可能的清晰和简洁，但在Objective-C中，清晰比简洁更重要
//清晰
insertObject:atIndex:
//不清晰，insert的对象类型和at的位置属性没有说明
insert:at:
- 不要使用单词的简写，拼写出完整的单词
//清晰
destinationSelection:setBackgroundColor:
//不清晰，不要使用简写
destSel:setBkgdColor:
- 命名方法或者函数时要避免歧义
//有歧义，是返回sendPort还是send一个Port？
sendPort
//有歧义，是返回一个名字属性的值还是display一个name的动作？
displayName
命名统一使用驼峰命名法；只采纳有广为人知含义的缩写，比如
info、msg、UI、HTTP这类。自造的缩写不被认可。总体的命名原则是清晰和一致，避免歧义。类名需要结合项目名称来命名，确保整个项目中的自定义类的名称开头是统一的，同样要确保类名需要大写字母开头。
类名命名需结合功能或者模块，并且尾部要带上该类的类型，比如
UIViewController的子类命名为JasonIndexViewController。
UIViewController 后缀添加“Controller”
UIView 后缀添加“View”
UIButton 后缀添加“Button"或者"Btn"
UILabel 后缀添加“Label"
一致性
- 整个工程的命名风格要保持一致性，最好和苹果SDK的代码保持统一。不同类中完成相似功能的方法应该叫一样的名字，比如我们总是用
count来返回集合的个数，不能在A类中使用count而在B类中使用getNumber。
命名方法
- OC的命名方法通常比较长，是为了让程序有更好的可读性，目的是为了可以当成一个句子的形式朗读出来，达到见名知意的效果
- 方法一般以小写字母打头，每一个后续的单词首字母大写，方法名中不应该有标点符号（包括下划线），有两个例外：
- 可以用一些通用的大写字母缩写打头方法，比如
PDF,TIFF等。 - 可以用带下划线的前缀来命名私有方法或者类别中的方法。
- 可以用一些通用的大写字母缩写打头方法，比如
如果方法表示让对象执行一个动作，使用动词打头来命名，注意不要使用do，does这种多余的关键字，动词本身的暗示就足够了：
//动词打头的方法表示让对象执行一个动作
- (void)invokeWithTarget:(id)target;
- (void)selectTabViewItem:(NSTabViewItem *)tabViewItem;
如果方法是为了获取对象的一个属性值，直接用属性名称来命名这个方法，注意不要添加get或者其他的动词前缀：
//正确，使用属性名来命名方法
- (NSSize)cellSize;
//错误，添加了多余的动词前缀
- (NSSize)calcCellSize;
- (NSSize)getCellSize;
对于有多个参数的方法，务必在每一个参数前都添加关键词，关键词应当清晰说明参数的作用：
//正确，保证每个参数都有关键词修饰
- (void)cycleScrollView:(SDCycleScrollView *)cycleScrollView didSelectItemAtIndex:(NSInteger)index
//错误，遗漏关键词
- (void)sendAction:(SEL)aSelector :(id)anObject :(BOOL)flag;
//正确
- (id)viewWithTag:(NSInteger)Tag;
//错误，关键词的作用不清晰
- (id)taggedView:(int)Tag;
不要用and来连接两个参数，通常and用来表示方法执行了两个相对独立的操作（从设计上来说，这时候应该拆分成两个独立的方法）：
//错误，不要使用and来连接参数
- (int)runModalForDirectory:(NSString *)path andFile:(NSString *)name andTypes:(NSArray *)fileTypes;
//正确，使用and来表示两个相对独立的操作
- (BOOL)openFile:(NSString *)fullPath withApplication:(NSString *)appName andDeactivate:(BOOL)flag;
命名通知
通知常用于在模块间传递消息，所以通知要尽可能地表示出发生的事件，通知的命名方式是：
code[触发通知的类名] + [ Did | Will ] + [动作] + Notification
举个栗子
NSApplicationDidBecomeActiveNotification
NSWindowDidMiniaturizeNotification
注释
文件注释
- 举个栗子
/*******************************************************************************
Copyright (C), 2011-2013, Andrew Min Chang
File name: AMCCommonLib.h
Author: Andrew Chang (Zhang Min)
E-mail: [email protected]
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-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.
********************************************************************************/
/*************************************************************
* Copyright (c) xxx科技有限公司
* All rights reserved.
*
* 文件名称: xxx
* 文件标识: xxx
* 摘要说明: xxx
*
* 当前版本: 1.0.0
* 作 者: CPX
* 更新日期:
* 整理修改:
*
***************************************************************/
文件注释的格式通常不作要求，能清晰易读就可以了，但在整个工程中风格要统一。
代码注释
- 方法、函数、类、协议、类别的定义都需要注释，推荐采用Apple的标准注释风格，好处是可以在引用的地方
alt+command+/点击自动弹出注释，非常方便
/**
* 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;
- 协议、委托的注释要明确说明其被触发的条件
// Individual rows can opt out of having the -editing property set for them. If not implemented, all rows are assumed to be editable.
- (BOOL)tableView:(UITableView *)tableView canEditRowAtIndexPath:(NSIndexPath *)indexPath;
UI布局规范
·建议项目统一使用Masonry和xib结合的方式布局。不允许出现直接设置frame的情况。如果是纯代码的项目，不允许出现xib和拉约束的情况。不允许纯storyboard开发。
· 提取方法，去除重复代码。对于必要的工具类抽取也很重要，这在以后的项目中是可以重用的。
· 尽可能的使用局部变量
· 尽量减少对变量的重复计算
· 尽量在合适的场合使用单例。使用单例可以减轻加载的负担，缩短加载的时间，提高加载效率。注意：并不是所有的地方都适用于单例
编码规范
- 使用
#pragma mark来分类方法，参考以下结构，通常将不常用的函数方法写在底部，这里强制要求懒加载必须写在底部
#pragma mark – Life Cycle
#pragma mark - Events
#pragma mark – Private Methods
#pragma mark - UITextFieldDelegate
#pragma mark - UITableViewDataSource
#pragma mark - UITableViewDelegate
#pragma mark - Custom Delegates
#pragma mark – Getters and Setters
- 枚举的定义参考系统定义枚举方式
typedef NS_ENUM(NSUInteger, UISearchBarStyle) {
UISearchBarStyleDefault, // currently UISearchBarStyleProminent
UISearchBarStyleProminent, // used my Mail, Messages and Contacts
UISearchBarStyleMinimal // used by Calendar, Notes and Music
}
-
if和case语句,不论if或者else下有一个还是多个语句，都必须带上大括号。同样case语句也是如此。
//正确
if (!error) {
return success;
}
//错误
if (!error)
return success;
或
if (!error) return success;
- 布尔值推荐写法
if (someObject) {
//...
}
if (![anotherObject boolValue]) {
//...
}
- 当需要提高代码的清晰性和简洁性时，三元操作符才会使用。
//推荐写法
NSInteger value = 5;
result = (value != 0) ? x : y;
BOOL isHorizontal = YES;
result = isHorizontal ? x : y;
//不推荐写法
result = a > b ? x = c > d ? c : d : y;
-
CGRect函数
//推荐写法
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;
- 当使用条件语句编码时，不要嵌套
if语句，多个返回语句也是OK
//推荐写法
- (void)someMethod {
if (![someOther boolValue]) {
return;
}
//Do something important
}
//不推荐写法
- (void)someMethod {
if ([someOther boolValue]) {
//Do something important
}
}
- 单例模式
//单例对象应该使用线程安全模式来创建共享实例
+ (instancetype)sharedInstance {
static id sharedInstance = nil;
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
sharedInstance = [[self alloc] init];
});
return sharedInstance;
}
资源文件规范
· 全部小写，采用下划线命名法，加前缀区分。所有的资源文件都需要加上工程前缀（小写形式）。
· 命名模式：可加后缀_small表示小图,_big表示大图，逻辑名称可由多个单词加下划线组成，采用以下规则：
用途_模块名_逻辑名称
用途_模块名_颜色
用途_逻辑名称
用途_颜色
| 说明 | 前缀（工程前缀示例MW） | 示例 |
|---|---|---|
| 按钮相关 | mw_btn_ | mw_btn_home_normal、mw_btn_red,mw_btn_red_big |
| 背景相关 | mw_bg_ | mw_bg_home_header、mw_bg_main |
| 图标相关 | mw_icon_ | mw_icon_home_location、mw_icon_input |
| 分割线相关 | mw_div_ | mw_div_home_location、mw_div_input |
| 默认相关 | mw_def_ | mw_def_home_location、mw_def_input |
版本规范
· 采用A.B.C 三位数字命名，比如：1.0.2，当有版本更新的时候，依据下面的情况来确定版本号规范。
| 版本号 | 说明 | 示例 |
|---|---|---|
| A.b.c | 属于重大更新内容 | 1.0.0 -> 2.0.0 |
| a.B.c | 属于小部分更新内容 | 1.0.2 -> 1.2.2 |
| a.b.C | 属于补丁更新内容 | 1.0.2 -> 1.0.4 |
其他规范
· 检测内存泄漏。可使用Instruments加上其他第三方工具辅助分析内存。