项目过程管理（十）开发规范

Git

git的用户名为自己名字的小写全拼，邮箱为公司邮箱，方便追溯提交者。命令行操作示例：

git config --global user.name myname
git config --global user.email [email protected]

git commit的log原则：

• 必须说明提交的意义，不能是简单无意义的文字
• bug fix应写上是解决哪个bug，可复制“bug系统”上的ID和标题
• 做需求应写是哪个需求；分批提交应写上完成了什么具体内容
• 每做一个任务（解bug、重构或做需求）就commit一次，不要一次commit里做了多个任务。方便做code review和代码回滚。

平时拉取代码，不准用git pull，要用git pull --rebase。杜绝merge信息，方便查找历史。下图是反例：

分支管理请参考《Git分支管理规范》。

代码规范

各技术组自己决定代码风格规范，可参考google、apple、facebook、alibaba、airbnb、microsoft任一家的。并可找些自动格式化和检查工具作为辅助。例如移动开发可参考《移动开发代码规范与格式化工具》。

代码的文件组织（目录结构）规范应在README.md中说明。

其它一些准则：

1. 类名、函数名、变量名仔细斟酌，要能代表意义，不要怕长。由此就尽量不要对这些东西写中文注释了，一是翻译一遍浪费时间，二是无意义地增加信息量减慢了看代码速度。
2. 遗留工作要写TODO。待优化的地方要写FIXME。
3. 同一功能的代码要做好内聚，不要学新手是把同一类型的代码放一起。
4. 没有用的代码都删掉，不要变成注释留在原地。特别记得要删除开发过程的调试代码。
5. 干掉所有warning！

文档规范

新项目必须画系统架构图、网络拓扑图等宏观设计的图，便于新同学或测试组同学理解。无论在哪里写的，最后都应该复制一份一同提交到代码仓库，例如放在代码的docs目录。

好的代码应该只需要描述宏观架构和设计思路就能让新人上手，细节的设计是通过代码注释和增强代码可读性来体现的。快速的迭代节奏不会有时间写详细设计，且变化太快也来不及更新文档。

README.md（代码说明）还可以包括这些内容：

1. 迭代历史：可包括开发人员和代码历史。
2. TODO list
3. 工具使用说明
4. 第三方依赖的参考文档URL
5. 特殊的设计、约定
6. 项目关联的文档地址，例如需求文档、服务器接口文档等
7. 各种系统的一些公用的低机密性账号密码，例如测试账号

前后端合作都以API为媒介，所以API文档是必须的。怎么设计API规范，可参考《Web API规范设计指引》。

Review制度

哪些情况应该主动请求review：

• 有可能破坏了整体的设计风格、规范
• 代码所属的功能非常重要，出错的话会造成公司业务重大损失
• 改动范围很大，会改到另外2个或以上同事写的较多代码

本节参考

《Git分支管理规范》
《移动开发代码规范与格式化工具》
《Web API规范设计指引》

本系列文章的目录：https://hursing.blog.csdn.net/article/details/88025790