前言

  本手册的旨在统一开发iOS的人员代码规范，现代软件的架构复杂性需要协同开发，在协同开发中由于人员差异，可能招聘自社会，也可能来源于学校，每个人都可能有自己的一套编程规范。也有的人员是从其他语言转做iOS开发，那也会有其他语言的代码规范。但作为iOS开发，希望大家统一标准。同时此标准并不是一成不变的，可以根据大家的反馈和意见进行实时更新修改。制定本手册主要是为了统一大家的开发标准。码出高效，码出质量。

本手册主要包含如下几个章节，编程规约，编程守则。

编程规约

命名风格

 命名的基本原则就是采用有意义的命名，能做到看到名称就能了解其意思，最好连注释都不需要。

  • 1、变量命名，遵循系统规范，如果是类私有成员变量，采用下划线作为前缀。如果是采用属性方式，则直接采用lowerCamelCase风格。
  • 2、代码中严禁使用拼音或者拼音与英文混合的方式命名，一些涉及中文拼音的除外（例如youku）。对于英文不熟悉的可以自行翻译。对于一些专用名词，可能会存在多种翻译，但一套代码中需要保持统一。例如飞控可以翻译为flying controller还可以翻译为flight control。
  • 3、类名使用UpperCamelCase风格，对于SDK项目建议采用公司名称作为类名的前缀。
  • 4、常量采用小写字母k开头，使用lowerCamelCase风格，例如kMeterToFeetValue，禁止使用宏来命名常量。
  • 5、对于图片资源，采用下划线分割的方式命名，命名规则为 模块名_功能_状态,例如：camera_take_photo_normal_icon@2x.png。同时资源也需要按照模块放到不同的文件夹中，文件夹同样采用下划线分割命名。

代码风格

1、大括号的使用约定，如果大括号内为空，则简洁地写成{}即可，不需要换行，如果是非空代码块则：

  • 1）左大括号前不换行。
  • 2）左大括号后换行。
  • 3）右大括号前换行。
  • 4）右大括号后如果有else则不换行。
  • 5）表示终止的右大括号则必须换行；

2、空格使用约定：

  • 1）if/for/while/switch/do等保留字与括号之间都必须加空格；
  • 2）任何两目、三目运算符的左右两边都需要加空格（包括=，&&，+等）；
  • 3）采用四个空格缩进方式，如果用tab，必须启用编辑器的tab自动转四个空格功能；
  • 4）函数方法直接需要空一行；
  • 5）为了区分代码段，或者成员变量，需要适当增加空行；

注释

  • 1、对于接口的.h文件，需要采用标准的apple doc风格的注释，这样便于生成标准的apple doc文档，快捷键为option+command+/。
  • 2、对于变量的注释，建议采用///<来描述。
  • 3、对于代码块分割，使用#param mark - 进行分割。
  • 4、FIXME:用于标识此处代码需要修改，或者代码有错误不能工作。最好增加修改方式；规范写法 // FIXME: (username) content，采用这种写法主要是为了区分作者，方便全局搜索。
  • 5、TODO: 用于标识此处代码需要完善或未实现，待实现的功能需要增加简单说明。
  • 6、MARK: 用于标记代码块或者分组代码。
  • 7、 MARK vs #pragma mark 两者作用一致，这里做如下区分，如果用于分组就用#pragma mark -标记；

版本控制

 现在基本都是采用git作为版本控制工具，对于code review建议增加gerrit服务器来做review。对于commit规范，好的Commit Message至少会带来如下好处：

  • 1）提高review效率；
  • 2）便于书写release note;
  • 3）便于后期自己查看和别人查看，如果随便书写，可能过了半年到一年，自己都看不懂了哦；

推荐的提交规范格式：

1
2
3
<module>: <brief message>  
<black line>  
<detail message>

brief message最好以如下关键字开头”FIXED” “IMPROVED” “ADDED” “CHANGED” “REFACTORING”。
如果你的修改包含了多出逻辑修改或者bug修正，修改分开多条提交message，一次提交不利于review和回滚。

编程守则：

包含一些日常开发中的最佳实践和不要踩的坑，这个可以提高开发效率，避免不必要的错误。

1、写出明显没有bug的代码，而不是没有明显bug的代码，对于这句话可以理解为要把已知问题暴露出来而不是隐藏起来，例如：

1
2
3
4
5
void function() {
    if (inputError) {
        return;
    }
}

很多人在修改别人代码的或者调试别人的bug的时候很容易就做如上处理，只是把错误直接屏蔽了，并未修正bug，同时也会把bug隐藏起来了。其实这个就类似于断言函数，断言函数在这种参数异常或者条件异常的时候其实是非常好用的，特别是多人合作的时候，我做了一个功能，需要别人调用，当别人传入数据或者本身代码异常的时候，用断言可以很好地调试。

2、非主线程操作UI，在iOS13上，非主线程操作UI会导致程序崩溃，建议在XCode中增加Main Thread Checker,这样就可以在开发过程中就发现此类错误。