第二版 2017.1.6
第三版 2018.8.29
以下规范基于 Coding Guidelines for Cocoa - Apple & 唐巧的博客
留白
- 使用tab而不是空格
- 使用留白划分程序逻辑块
- 方法名过长时注意换行：尽量让代码保持在120列之内; 通过设置 Xcode > Preferences > Text Editing > Show page guide，来使越界更容易被发现
应该
// blocks are easily readable
[UIView animateWithDuration:1.0 animations:^{
// something
} completion:^(BOOL finished) {
// something
}];
不应该
// colon-aligning makes the block indentation hard to read
[UIView animateWithDuration:1.0
animations:^{
// something
}
completion:^(BOOL finished) {
// something
}];
不应该
if([MePagePushManager shareInstance].isPushRegiste
&&[MePagePushManager shareInstance].isPushAvailable){
[[MePagePushManager shareInstance] updatePushToken];
}
命名
目的:简洁易懂
- 使用驼峰格式命名，请不要使用驼峰和XXX_XXX混用，统一命名格式；
- 文件命名前缀：
- 当与系统和第三方命名冲突时添加前缀以示区分；如:WBImageView
- 当被提供为SDK时，使用前缀，以示归属；如:SiaoFloatView;在项目中可用Bridge或者子类方式转换文件名,如:上述的SiaoFloatView,可用Bridge.h宏文件替换命名,或者 子类化出FloatView;
- 文件、类、变量命名应使用英文名称
- 不使用拼音；
- 不使用毫无意义的简短的英文字母，名称应尽量描述出含义；
- 请勿使用个人名字相关的命名；第三方框架除外.
- 命名单词尽量写全；如:button,view.
- 类名首字母大写，方法首字母小写，方法中的参数首字母小写，同时尽量让方法的命名读起来像一句话，能够传达出方法的意思；
- 以上命名，做到顾名思义,这样的方法名和变量名无需添加注释。
- 方法命名应该和apple官方命名一致
应该
- (UIView *)viewWithModel:(Model *)model other:(id)other {
NSInteger i = height + 5 * 2;//应该用空格隔开
}
不应该
-(UIView*)viewWithModel:(Model *)model other:(id)other {
NSInteger i = height+5*2;
}
应该
UIButton *settingsButton;
CGFloat view_height;//VIEW_HEIGHT;
不应该
UIButton *setBut;
不应该
CGFloat View_Height;
- 点击事件命名didClickSendButton; didTapBoxView; 等
- 定义网络请求，requestXXX，解析网络请求dealWithXXXX;
- (void)requestHotlistData:(BOOL)loadMore completion:(void(^)(BOOL success))completion;
- (void)dealWithHotListResponseWithData:(NSArray *)data;
文档和代码组织
- 数字注释出含义
- 参数不允许为nil时，加注释
- 使用Use #pragma mark对功能实现和协议实现分组，如下示例
- 清除警告，个人的提醒用//@todo yourname or //@waring yourname代替，这样只需要在项目里搜索 @todo yourname就可以找到，团队协作 在不影响他人的情况下协同开发；需要提醒大家的才用#warning ,保持项目的整洁，及时清除警告。
- 文件自上到下从优先级以及包含与被包含的关系排列,禁止无须排列;
应该:
image.png
不应该
image.png
if (model.more_info.text.length > 0) {
height += comments.count > 0 ? 6.0 : 0.0;//有回复且有moreInfo 有一个上边距 6
height += [self moreInfoHeight];
} else {
height -= 1;//由于为了适配有表情的行高(+2) 这里减去2
}
#pragma mark Properties
@dynamic someProperty;
- (void)setCustomProperty:(id)value {}
#pragma mark Lifecycle
+ (id)objectWithThing:(id)thing {}
- (instancetype)init {}
//@todo xiaodong
//@warning xiaodong
声明
- 如果属性的可修改性是一个实现细节，声明不可修改属性。这是一个合理的显式的声明实例变量的原因
- 如果一个属性只在init内被赋值了一次，那么就声明为readonly
- 如果返回可修改对象，并且实现中不修改该对象，则属性声明为copy, strong应该仅用于暴露一个可修改对象
- 使用[setupProperty]给需要初始化的变量初始化；
- _property&self.property
- 懒加载的使用, 需要使用懒加载才使用,不应该为了代码简洁而使用.
大家知道，self.property 其实是调用了类的 [self property] 方法，所以这其实是有一层方法调用的隐藏，很多时候，我们需要延迟初使化一个类成员的时候，就会把这个成员的初使化方法写在这个 [self property] 方法的实现中。
那么问题来了，当你在阅读别人代码时，看到 self.property 的时候，你会想：这里会不会有一些隐藏的函数实现？于是你需要跳转到其方法实现中去查找。但是在实际开发中，大部分的 property 其实是使用编译器自动生成的 Getter 和 Setter 方法，于是你会找不到实现，这个时候，你才知道：“哦，原来这段代码并没有做自定义的成员初使化工作”。
这种默认的隐藏在代码中多了，会影响代码的阅读和维护。其实大部分的类成员变量都需要在类初使化方法中赋值，大部分的 UIViewController 的成员变量，都需要在 viewDidLoad 方法中赋值。那既然这样，不如直接在相应的方法中用一个名为 setupProperty 方法直接进行初使化。这样的好处是，代码的可读性更好了，self.property 只有需要延迟初使化的情况下才被使用。
@property (attributes) id<Protocol> object;
@property (nonatomic, strong) NSObject<Protocol> *object;
@implementation WKHotSearchViewController{
NSObject *_object;
}
- Constructors 应该返回instancetype而不是id
不应该
- (instancetype)initWithStyle:(UITableViewCellStyle)style reuseIdentifier:(NSString *)reuseIdentifier
{
self = [super initWithStyle:style reuseIdentifier:reuseIdentifier];
if (self) {
[self.container addSubview:self.userIconImg];
[self.container addSubview:self.nickNameLab];
[self.container addSubview:self.timeLab];
[self.container addSubview:self.contentImg];
[self.container addSubview:self.contentLab];
[self.container addSubview:self.bottomLine];
[self.contentView addSubview:self.container];
[self addMasonry];
}
return self;
}
常量
- 常量是容易重复被使用和无需通过查找和代替就能快速修改值。
- 常量应该使用static来声明而不是使用#define，除非显式地使用宏。
static NSString * const IDENTIFY = @"weibo.com";
static CGFloat const CELL_HEIGHT = 50.0;
枚举
- 按照系统的命名方式
应该：
typedef NS_ENUM(NSInteger, PushType) {
PushTypeUnknown,
PushTypeArticleRemotePush, // 远程Push打开正文
PushTypeArticleLocalPush, // 本地Push打开正文
};
注释
- 应做到尽量代码“自解释”，而不需要再编写注释。
- 当需要注释时，注释应该用来解释这段特殊代码为什么要这样做。
- 不注释代码块，无用的代码直接删除
- 不要一行一个注释,单行注释,可加在代码末尾;
- 注释不是分割行的标记!
应该
@property (nonatomic,strong) UILabel *nickNameLab; // 昵称 + 赞了你的评论
不应该
/* headerTop */
WBHeadlineHeaderView *articleHeaderView;
/* headerMiddle */
UIView *headerMiddleView;
WBArticleMedileHeaderView *continuseView;
- 不清楚MiddleView是什么作用,加了无意义,等于没加;
控制结构
- 除if (xxx) return; 的用法，if必须加括号
- 所有左括号应该和关联的表达式同一行，结尾换行
- 关键词和括号间加空格
- 括号和它包括的内容间不加空格
if (somethingIsBad) return;
if (something == nil) {
// do stuff
} else {
// do other stuff
}
- 黄金路径，早返回
应该
- (void)someMethod {
if (![someOther boolValue]) {
return;
}
//Do something important
}
不应该
- (void)someMethod {
if ([someOther boolValue]) {
//Do something important
}
}
异常和错误处理
- 不用使用异常做控制流
- 表示错误，使用NSError **参数,或者给ReactiveCocoa signal发一个错误
- 方法参数不匹配时，使用NSAssert
- 循环引用
对象语法
- 数组和字典对象文法内容两边使用一个空格
- 字典文法中，键值和冒号之间不留空格，值和冒号之间使用一个空格
- 数组和字典setObject时候需要保证object非nil
NSArray *theStuff = @[@1, @2, @3];
NSDictionary *keyedStuff = @{GHDidCreateStyleGuide: @YES};
- 更长或者更复杂的文法应该分成多行（可选以逗号结尾）
NSArray *theStuff = @[
@"Got some long string objects in here.",
[AndSomeModelObjects too],
@"Moar strings."
];
NSDictionary *keyedStuff = @{
@"this.key": @"corresponds to this value",
@"otherKey": @"remoteData.payload",
@"some": @"more",
@"JSON": @"keys",
@"and": @"stuff",
};
类的结构
graph TD
A[LifeCycle] -->B(Request)
B -->C(UITableViewDelegate&DataSource)
C -->D(...)
D -->E(Setter&Getter)
- 注意Lazy init的用法
- 精简VC
第三方库引入
－ 引入第三方库前，需要充分调研该库的质量，引入github的库，原则上应该star在500＋以上才考虑
－ 引入的库若支持Pods管理，以Pods来组织代码
－ 引入的库应该保持代码不变，在库的上层进行自定义，而不应该修改库本身
引用文件
- 在.h中尽量使用@class(如果不需要知道引用文件的具体属性)，在.m文件中使用#import
扩展
- 扩展应该按照所提供的功能命名，不要创建保护伞拓展
- 扩展方法一定要加前缀
- 如果你想给子类或者单元测试暴露私有方法，使用 Class+Private命名创建一个分类
- (void)pf_viewDidLoad
{
[self pf_viewDidLoad];
}
兼容64位
- 整型的声明使用NSInteger
- 浮点使用CGFloat(UI相关)和double
- 字符串占位符不再使用%d, %ld, 将对应的整型使用对象文法包装，并使用%@的打印 [NSString stringWithFormat:@"%@", @(intVar)]
- 枚举定义采用新风格(NS_ENUM)，并指定类型为NSInteger
