@FoxBabe
2015-04-07T23:28:06.000000Z
字数 7250
阅读 3036
本文档目的在于定义iOS开发过程中的编码规范,统一编程风格,提高代码的可读性与团队编码效率,避免团队开发可能造成的混乱。
本文档规范使用于团队内使用Objective-C开发的工程项目。
说明:
* Resource存放资源文件,图片、字体和配置文件等;
* Macro宏定义目录,存放程序的常用宏定义和第三方参数的宏定义;
* Helper常用帮助工具汇总;
* Categroy常用类的扩展文件;
* NetWork网络框架工具
* UI常用公共控件
* Depends第三依赖库文件夹
* Models模型对象
* Views项目中自定义的视图和控件
* Controllers项目中的控制器,根据实际业务再进行分组
头文件布局优先顺序,从上到下递减
* .h头文件描述,描述参考注释模块
* 引用的头文件
* 常量定义和宏定义,如常用的通知、常量和公用宏的定义
* 类和协议说明,使用@class和@protocol来说明某个类型为类或协议
* 类定义,即定义@interface和其成员变量
* 类属性,在@interface外定义类的属性
* 类方法和实例方法
* 协议定义
* 扩展类别
实现文件布局优先顺序,从上到下递减
* .m实现文件描述,描述参考注释模块
* 引用的头文件
* 常量定义的实现
* 内存管理,目前采用ARC编码,这里的内存指在dealloc文件中移除通知,清空特殊数据等,此步可选。
* 数据初始化和界面初始化
* 详情实现方法,使用#parma mark 的 Detail methods来分组
* 其他归类方法的分组
* 自定义类的协议实现方法,按照不同的协议分组显示
* 系统类的协议实现方法,按照不同的协议分组显示
* 扩展类别的实现方法
实现文件中,务必定义初始化方法,变量在使用之前,都必须统一进行初始化赋值;对于设计界面的类,如集成View或ViewControler,需要添加界面初始化的方法。
#!objective-c
extern ushort APIDefaultPageSize; // 还行,能明白意思了
extern ushort APIDefaultFetchPageSize; // 加上些限定更好一些
extern ushort APIFetchPageSizeDefault; // 再好些,把重要的往前放
YHToolbarComment // 不推荐
YHCommentToolbar // OK,把类型(toolbar)置后
缩写 | 含义 |
---|---|
btn | 按钮 |
hlbtn | 按钮的高亮 |
bg | 背景图片 |
hlbg | 背景图片的高亮 |
img | 图片 |
icon | 图标 |
#!objective-c
personalcenter_edituserinfo_btn //个人中心编辑用户信息按钮
common_save_btn //共用的保存按钮
例如:
#!objective-c
// OK
- (NSString *)name;
// 糟糕,应用上面的写法
- (NSString *)getName;
// OK,但极少使用
- (void)getName:(NSString **)buffer range:(NSRange)inRange;
// OK
- (NSSize)cellSize;
// 糟糕,应用上面的写法
- (NSSize)calcCellSize;
// 对 controller 做一般设置,OK
- (void)setupController;
// 列出具体设置的内容,更好
- (void)setupControllerObservers;
// 糟糕,set 专用于设置属性
- (void)setController;
#!objective-c
NSApplicationDidBecomeActiveNotification
NSWindowDidMiniaturizeNotification
NSTextViewDidChangeSelectionNotification
#!objective-c
UILabel *userNameLabel;
UIButton *loginBtn;
#!objective-c
#define PI 3.1415926
除以上规则约定外,其他常量约定了以下前缀:
前缀 | 含义 |
---|---|
k | 宏常量 |
CDEN | CoreData entity name |
UDK | User Default Key |
缩写 | 含义 |
---|---|
URL | 链接地址 |
x | 坐标 |
y | 坐标 |
w | 宽度width |
h | 高度height |
vc | 控制器ViewController |
v | 视图View |
dic | 字典Dictionary |
#!objective-c
- (void)doSomethingWith:(GTMFoo *)theFoo rect:(NSRect)theRect
interval:(float)theInterval {
}
- (void)short:(GTMFoo *)theFoo longKeyword:(NSRect)theRect
evenLongerKeyword:(float)theInterval {
}
#!objective-c
//OK
[myObject doFooWith:arg1 name:arg2 error:arg3];
[myObject doFooWith:arg1
name:arg2
error:arg3];
//糟糕
[myObject doFooWith:arg1 name:arg2 // some lines with >1 arg
error:arg3];
[myObject doFooWith:arg1
name:arg2 error:arg3];
[myObject doFooWith:arg1
#!objective-c
// 糟糕
-(void)methodName:(NSString *)string;
// OK
- (void)methodName:(NSString *)string;
// 糟糕
if ( a < b ) {
// something
}
// OK
if (a < b) {
// something
}
// OK
(someValue > 100)? YES : NO
#!objective-c
- (void)methodName:(NSString *)string {
↑空格 ↑空格,推荐花括号在一行
if () {
空格↑ ↑空格,花括号不要另起一行
}
else {
要换行↑ ↑空格,花括号不要另起一行
}
}
说明:
Xcode 默认的花括号位置是这样的:方法内部的各种补全都是在同一行的;方法定义的比较混乱,默认模版另起一行,但从 Interface Builder 中连线生成的方法在同一行的。
考虑到 Xcode 的默认行为,方法内部要另起一行,方法所在行不强制定死。另外,模版可以定制,而 IB 生成的代码不可定制,所以不另起一行的写法优先。
另起一行的写法在代码折叠后非常难看。
长表达式(超过100列)要在低优先级操作符处拆分成新行,操作符放在新行之首(以便突出操作符)。拆分出的新行要进行适当的缩进,使排版整齐。
Google的80字符的标准有点少,这导致过于频繁的换行(Objectve-C的代码一般都很长)通过 “Xcode => Preferences => TextEditing => 勾选Show Page Guide / 输入100 => OK” 来设置提醒
函数(方法)声明时,类型与名称不允许分行书写。
#!objective-c
//OK
extern double FAR CalcArea(double dWidth, double dHeight);
//糟糕
extern double FAR
CalcArea(double dWidth, double dHeight);
#!objective-c
typedef enum
{
SDWebImageRetryFailed = 1 << 0, //无法下载时,列入黑名单中后,将不会再重新下载
SDWebImageLowPriority = 1 << 1, //默认情况下,图像下载期间用户界面相互作用开始,这标志禁用此功能,
SDWebImageCacheMemoryOnly = 1 << 2, //禁止磁盘缓存
SDWebImageProgressiveDownload = 1 << 3 //这个标志使渐进式下载,图像显示逐步在下载期间作为一个浏览器会做的。
} SDWebImageOptions;
#!objective-c
typedef NS_ENUM(NSInteger, TTITextAlignment) {
TTITextAlignmentLeft = 0, // 左对齐
TTITextAlignmentRight = 1, // 右对齐
TTITextAlignmentCenter = 2, // 居中
}
参考苹果最新的API头文件,推荐采用第二种来进行定义。关于枚举类型的命名和对应只命名作如下约定。
项目中常见block定义方式,如下所示:
#!objective-c
typedef void(^SDWebImageCompletedBlock)(UIImage *image, NSError *error, SDImageCacheType cacheType);
typedef void(^SDWebImageDownloaderProgressBlock)(NSUInteger receivedSize, long long expectedSize);
block类型命名规则约定:[类名]+[状态](可选 + [条件描述,如withxxx])+ Block。
使用#import引入Ojbective-C和Ojbective-C++头文件,使用#include引入C和C++头文件。
程序编码过程中,我们可以通过一些标注,来提示自己有些事情是需要以后来处理的,为了防止遗漏,加上TODO、FIXME、!!!、???和waring是很有必要的,我们可以通过下面的方式添加对应的提醒:
#!objective-c
// TODO: 处理异常情况
// FIXME: 此处需要清楚缓存
// !!!: 此处逻辑不严谨,待完善
// ???: 这块的实现上还存在难度,待研究跟进
#warning 此处在特定情况下会出现异常,提交版本前一定要处理
前四种为备注说明,并且在预览方法时会清晰显示出来,后面warnning,是在编译程序后都会直接作为一个警告出现在编译结果中。
在实际开发中,如果开发到中途,要需要处理的,务必加上对应的标志,防止再次来编辑时遗漏。另外,在提交版本前,一定要对这些标志进行一次检查,warnning能很明显的发现,其他四种可以采用插件Xcode插件XToDo(https://github.com/trawor/XToDo)来查找。
头文件说明示例:
#!objective-c
//
// TTiRecordStatueBar.h
// CustomStatueBar
//
// Created by Fox on 14-7-16.
// Copyright (c) 2014年 翔傲信息科技(上海)有限公司. All rights reserved.
注意:
* 个人创建的类必须修改为当前用户
* 版权同意为:翔傲信息科技(上海)有限公司
1. 方法注释只需要在申请方法的地方添加,实现时不需要添加;
2. 注释使用中文;
本文档编写过程中参考了如下编码规范文档: