代码规范

第二版 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 ,保持项目的整洁,及时清除警告。
  • 文件自上到下从优先级以及包含与被包含的关系排列,禁止无须排列;

应该:


代码规范_第1张图片
image.png

不应该


代码规范_第2张图片
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 object;
@property (nonatomic, strong) NSObject *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

你可能感兴趣的:(代码规范)