# 项目进阶规范
本规范指定了一些判断和实施难度较高的规范要求，项目成员应当根据自己的能力尽力达成本规范所要求的内容。在阅读本规范前，应先阅读并牢记[项目基本规范](./README.md)

## 一、注释规范
规范注释是规范代码的第一步，写不好注释的人，就算技术能力再怎么高，也难以适应团队化开发

### 1、注释的基本使用
1. 多行注释：多行注释通常用于对整个代码文件进行说明，或是在重要的函数和数据结构前对其进行详细说明。多行注释有规定格式的，应当按照规定格式来编写
2. 单行注释：单行注释应用于绝大部分场合，包括对函数的进行说明，对接下来的代码进行说明，或者用于做特定的标记等
3. 代码后注释：指和代码在同一行，并在代码后的单行注释。代码后注释通常用于对变量进行说明，或者对本行内容进行补充性说明
在项目中，只允许使用以下几种注释格式之一
4. 代码中注释：指和代码在同一行，并且不在代码后的注释。除了用于占位以外，应尽量避免使用代码中注释
5. TODO标记：可以应用在任何代码注释中，并且标记在注释的最前方。TODO标记用于占位，提示开发者应当在该位置做的事情。在由于某些原因无法直接完成全部代码，或者为了赶时间暂时提交了临时使用的代码的时候。就可以用TODO标记来占位，一个典型的带有TODO标记的注释：// TODO:这里有漏洞，需要修改

### 2、应当使用注释的地方
1. [项目基本规范](./README.md)里规定了必须要使用注释的地方
2. 对全局变量和其他使用范围较大，并且变量名不能做到一目了然的变量，应当使用代码后注释
3. 函数内部分为多个代码块的时候，对无法一眼看懂的代码块应当添加对应注释
4. 代码中需要提醒开发者和维护者注意的地方，应当添加注释
5. 对比较复杂的表达式或者逻辑判断，建议添加注释

### 3、不应该使用注释的地方
1. 注释内容过多，规模过大的，应当单独建立文档进行说明，而不是作为注释放在代码文件中
2. 添加了注释之后对于阅读代码没有任何帮助的注释，不建议添加
3. 连续而琐碎的注释会影响阅读代码时的流畅性，如果连续而琐碎的注释太多，建议整理好之后放在一个语句块的前面

### 4、注意事项
1. 注释内容应当尽可能的清晰明确，避免使用函数不清的字句
2. 注释必须和代码保持同步，修改代码之后应当重新确认一下注释，并根据具体情况修改注释

## 二、代码规范

### 1、基本要求
1. 除非没有更好的替代方案，否则禁止使用全局变量
2. 对其他文件的引用，以及变量声明。尽可能的统一放在对应代码块和代码文件的头部统一管理
3. 在同一个项目内应当使用严格统一的语法来编写代码

### 2、代码分块
1. 在代码中，应该适当的使用空行来对代码进行分块
2. 在代码块中，代码的功能应当清晰明确，不能把不同的代码逻辑混在一起交替执行
3. 代码块不宜过长，通常一个代码块应当限制在10个语句之内
4. 业务复杂并且需要大量调用其他函数的来完成业务的单个函数内，应尽量将对外调用整合起来，以尽可能的避免一行一个代码块的情况出现

### 3、代码通用性
1. 数据和代码逻辑应当分离，尽可能避免在代码逻辑中使用写死的数据
2. 适当的使用中间数据，可以极大的提升模块的独立性，并减少对其他模块的依赖
3. 当进行单个模块开发的时候，尽量避免将依赖关系混入到模块逻辑中

# 文档修订记录
* 2019/9/5：初版