# 项目基本规范

本规范指定了所有项目通用的基本要求，**所有人必须严格遵守本规范进行开发**。根据项目，开发者除了本规范以外，还需要遵守相应类型的项目规范。<br />

## 重要
**以下所有要求均不追溯至需求生效之前的代码和项目，部分规则不适用于第四代之前的Node.js后端和旧版前端页面**

## 1、涉密内容
1. **严禁往代码仓库上直接上传涉密敏感内容。包括：正式站和测试站的各种服务的账号，密码，key；正式服务器的内外网IP地址；个人账号密码等**
2. 对于涉密内容，可以使用环境变量的，使用环境变量；不能使用环境变量的，统一放到单独文件里，然后把涉密文件添加到git忽略列表避免上传；以上方法皆不方便的，可以考虑存放到数据库中

## 2、注释和说明
1. 所有注释必须和实际代码内容匹配，要严格避免复制文件对代码进行修改之后不修改注释的情况
2. 每个项目必须在根目录下有readme.md对项目整体进行说明
3. 当前目录下有超过7个子目录或文件的情况下，必须添加readme.md对各目录和文件进行整体说明，但是有额外文档或者目录下的文件是自动生成的除外
4. 每个代码文件都要有整个文件的注释，并且尽可能放在文件顶部。在readme.md里面有说明的可以除外
5. 每个函数都应该有至少一行注释和函数声明放在一起。但是函数总行数小于等于5行的可以除外
6. 禁止使用注释来代替删除，并将其应用于大块的废弃代码

## 3、编码规范
1. 必须显式声明变量，而无论使用的语言是否支持隐式变量声明
2. 单个函数不能超过100行，并应尽量避免超过50行（含空行，不含注释），当单个函数太长的时候，则将其拆分为多个功能不同的子函数
3. 代码缩进必须对齐，并且统一使用半角空格实现缩进
4. 代码缩进不允许超过7层，并应尽量避免超过5层（按对齐线的数量计算），当缩进过多时，则将其拆分为子函数或是修改代码结构。但是JSON数据结构的缩进层级不受本要求限制
5. 在同一个代码文件里面，不允许有2个或2个以上相似度超过75%的函数存在，除非函数本身行数小于等于5行
6. 单行代码不允许超过300个字符，若超过的，应当在合适的部位加入换行。但是单行内容本身就是一个超长字符串的例外
7. 单行代码不超过50个字符的单个语句必须写在同一行里面，单行代码不超过100个字符的单个语句应当尽量写在同一行里面，应当尽可能的写在同一行里面。例如：let obj = { key, item }这种代码，就不能写成4行，而应该写在1行里面
8. 不能连续使用超过5级的子对象，并尽量不大于3级。在层级过高时，使用一个中间变量来让代码更加清晰友好。例如obj.sub1.sub2.sub3.sub4.sub5.sub6，可增加中间变量let subObj = obj.sub1.sub2.sub3，然后再使用subObj.sub4.sub5.sub6
9. 循环嵌套最多3层，超过3层的必须改用其他方法实现业务逻辑

## 4、命名规范
1. 变量名的长度不允许超过20个字符，并应尽量控制在10个字符以内；函数名的长度不允许超过40个字符，并应尽量控制在20个字符以内
2. 函数和变量命名时应当尽可能使用含义准确的英文或英文缩写，实在不方便的也可以使用拼音或者拼音首字母。但是拼音和英文混用时，必须是拼音缩写在前，英文单词在后。例如协议文档，可以命名为xyDoc，但是不允许命名为xieYiDoc
3. 除了[常用变量名及缩写](./常用变量名及缩写.md)里规定的变量名以外。禁止使用单个字母作为变量名，除非该变量仅出现于声明之后的最多10行代码以内
4. [常用变量名及缩写](./常用变量名及缩写.md)里规定的变量名不得用于表达其他含义
5. 除了局部变量和内部函数以外，所有函数和变量的命名应当清晰明确而不能过于宽泛。比如item和data这类命名，可以出现在单个文件内部，或者作为一个父对象的属性名，但不能单独跨文件使用
6. 每个文件的文件名必须清晰明确，不允许使用过于宽泛的文件名，比如item和page
7. 变量和函数的命名应当精简，不允许有过多冗余信息。比如父对象是userData，然后里面的函数又命名为getUserData，这种情况就需要把函数名称精简
8. 目录和代码文件命名应当精简，不允许有过多冗余信息。比如目录本身是users，然后下面的文件名字又叫做usersXXXX，这种情况就应该把文件名精简

## 5、Git库管理规范
1. 每次提交代码必须附带注释，并且注释必须有清晰的指向性含义。比如不能使用“修正一个BUG”这样的注释，而必须写清楚“修正了XX系统的一个BUG”
2. 所有人禁止在本地直接修改master分支，master分支仅允许项目维护者在远程库操作合并
3. 所有人禁止在本地直接修改test分支，test分支必须在远程库操作合并
4. 项目维护者以外的开发者禁止在本地直接修改develop分支，项目维护者仅在进行少量修改时允许在本地直接修改develop分支并推送。develop分支可以在远程库操作合并
5. 在给项目追加新功能时，应以master为源分支新建以feature-开头的分支，如feature-xxxSystem。在完成开发后，首先应将其提交到远程库，然后合并到develop分支进行开发者测试，开发者测试通过后再将其合并到test分支进行全面测试。测试没问题之后申请合并到master分支等待发布
6. 在修复项目线上的bug时，应以master为源分支新建以fix-开头的分支，如fix-ch190903。在完成修改后，将其提交到远程库，然后在远程库合并到develop或者test分支进行测试，测试完成以后申请合并到master分支并通知项目维护者进行合并发布
7. 项目维护者必须严格按照[项目tag管理规范](./项目tag管理规范.md)来管理tag

## 6、测试规范
1. 新功能必须先放到develop分支上进行测试，经过完整功能性测试之后确定没有问题才能合并到test分支
2. 新功能在放上test分支之后，必须经过简单的功能性测试，确认功能可以运行之后才能通知对接人进行测试
3. bug修复分支直接在test分支上进行测试，测试完没有问题之后再合并到develop分支和master分支

# 扩展内容
* [常用变量名及缩写](./常用变量名及缩写.md)(2019/9/6)
* [node.js后端项目规范](./项目规范_node.js后端.md)(待编辑)
* [vue项目规范](./项目规范_vue项目.md)(待编辑)
* [小程序项目规范](./项目规范_小程序.md)(待编辑)
* [安卓原生项目规范](./项目规范_安卓原生.md)(待编辑)
* [苹果原生项目规范](./项目规范_苹果原生.md)(待编辑)
* [项目tag管理规范](./项目tag管理规范.md)(待编辑)

# 文档修订记录
* 2019/9/6：初版
* 2019/9/24：增加涉密内容的规定