完成注释方面的规范编写

README.md

@@ -7,42 +7,146 @@
 ## 基本目标
 
 本规范期望达到的目标有以下几个
-* 让项目易于维护
-  通过统一的代码规范和约定，让项目代码变得更容易阅读。让任何一个具备相关知识的开发者都能够在尽可能短的时间内上手进行基本的开发和修改。
-* 控制代码质量
-  通过强制性的代码规范和约定，避免一些容易出现在开发中的影响到代码质量的问题。
-* 降低部署风险
-  通过执行代码规范和约定，来降低从测试到部署的过程中出现问题的风险。
+* **让项目易于维护：** 通过统一的代码规范和约定，让项目代码变得更容易阅读。让任何一个具备相关知识的开发者都能够在尽可能短的时间内上手进行基本的开发和修改。
+* **控制代码质量：** 通过强制性的代码规范和约定，避免一些容易出现在开发中的影响到代码质量的问题。
+* **降低部署风险：** 通过执行代码规范和约定，来降低从测试到部署的过程中出现问题的风险。
 
 ## 项目代码编写原则
 
 每个项目参与者在进行项目开发时，都应该尽其所能的遵守以下几个原则
 ### 开始开发前
-  * 不要立即动手
-    拿到需求后不要马上进行编码。先进行思考并和产品沟通，**确保自己确实理解了需求，并对整个流程了然于胸之后，再动手**。
-  * 先进行询问和检索
-    在进行开发之前，先了解一下想要的东西是不是已经有了类似的实现，或者干脆就不需要实现。**避免让开发变成重复造车轮**。
+  * **不要立即动手：** 拿到需求后不要马上进行编码。先进行思考并和产品沟通，**确保自己确实理解了需求，并对整个流程了然于胸之后，再动手**。
+  * **先进行询问和检索：** 在进行开发之前，先了解一下想要的东西是不是已经有了类似的实现，或者干脆就不需要实现。**避免让开发变成重复造车轮**。
 ### 开发过程中
-  * 随时注意自己的编码是否易读
-    尽可能的做到**每一行代码都能让人一眼看懂**，而不需要花费额外的时间去理解。
-  * 随时注意自己的脚本和函数是否功能单一而且明确
-    如果需要实现复杂的逻辑，就将其拆成多个简单功能来调用。**确保每个函数的功能能用一句话说清楚**。
-  * 随时注意避免代码过度耦合
-    避免重复造车轮，最关键的就是在制造车轮的时候考虑到**让其他人也能使用**。
-  * 随时注意代码长度是否过长
-    如果是单个函数代码过长，考虑拆成几个子函数；如果是单个文件过长，考虑拆成多个文件；单个模块文件太多的，考虑建立一个子目录来存放文件。
+  * **随时注意自己的编码是否易读：** 尽可能的做到**每一行代码都能让人一眼看懂**，而不需要花费额外的时间去理解。
+  * **随时注意自己的脚本和函数是否功能单一而且明确：** 如果需要实现复杂的逻辑，就将其拆成多个简单功能来调用。**确保每个函数的功能能用一句话说清楚**。
+  * **随时注意避免代码过度耦合：** 避免重复造车轮，最关键的就是在制造车轮的时候考虑到**其他人也可能会用到**。
+  * **随时注意代码长度是否过长：** 如果是单个函数代码过长，考虑拆成几个子函数；如果是单个文件过长，考虑拆成多个文件；单个模块文件太多的，考虑建立一个子目录来存放文件。
 ### 开发完成后
-  * 至少完成一次代码自审
-    在代码完成之后，**必须重新审查一遍**。以便于补充注释，修改错漏，删除多余的打印输出。
-  * 上传之前必须进行检查
-    每次推送代码到服务器之前，先确认当前代码能否**正常**运行，确认之后才能上传。
-  * 每次提交都要明确的说明修改了什么
-    除了合并代码以外，在提交的时候应该明确的说明自己这次的提交修改的内容。**不要在提交的时候随意编写毫无意义的提交说明**
+  * **至少完成一次代码自审：** 在代码完成之后，**必须重新审查一遍**。以便于补充注释，修改错漏，删除多余的打印输出。
+  * **上传之前必须进行检查：** 每次推送代码到服务器之前，先确认当前代码能否**正常**运行，确认之后才能上传。
+  * **每次提交都要明确的说明修改了什么：** 除了合并代码以外，在提交的时候应该明确的说明自己这次的提交修改的内容。**不要在提交的时候随意编写毫无意义的提交说明**
 
 **以上要求可能会随时增加，请随时关注本规范的最新版本**
 
-## 代码规范
-
+***
 ## 注释规范
 
+规范注释是规范代码的第一步，写不好注释的人，就算个人技术能力再怎么高，也难以适应团队化的开发。
+
+### 1、注释格式
+在项目中，只允许使用以下几种注释格式之一
+1. 多行注释
+```js
+/**
+* 这是多行注释，通常用在每个文件的头部或者函数头部，也可以用在其他任何需要大段注释的地方。
+* 本规范并不对多行注释的行首星号和缩进之类的细节做任何要求，但是注释仍然需要遵循基本的规范。
+* 注意：以下所有注释内容都是可选的，但是一旦使用，就必须符合对应的格式要求。
+* @param {string} something 这是对参数的注释，格式是：@param {参数类型} 参数名称。在本例子中就是说明了一个名字叫做something的string类型参数。在接受的参数比较复杂时，最好在之后的文本说明中追加具体说明。
+* @return {object} 这是对返回结果的注释，格式是：@return {返回类型}。在本例子中就是说明了接口或函数的返回结果是一个对象。
+* @author 陈昊 这是对作者的注释，通常用在单个脚本文件的头部，说明了这个脚本的函数的编写者是谁。一般除非重写，否则不要覆盖最初作者的名字。
+* @version 1.0.190314 这是脚本/函数的版本号，共有三级。第一级从1开始，在单次修改（单纯的增加不算）超过1/3时建议修改第一级版本号。第二级版本从0开始，只要对脚本进行了功能性方面的修改之后，就建议修改该版本号。第三级是脚本的最后一次修改的日期，每次修改都应该修改。不建议对不是特别重要的脚本使用该注释。
+* @description 这里添加具体描述。实际上一般不需要使用@description关键字，直接把说明内容写在后面就好了。
+*/
+```
+2. 单行注释
+```js
+// 这是一个独立的单行注释，可以用于几乎所有需要注释的场合，单行注释要写得简单明了。如果说明内容太长的话则建议换成多行注释。
+```
+
+3. 代码后注释
+```js
+let tmp = null; //这是单行代码后的注释，通常用于变量说明和if分支说明。内容和单行注释一样要求精简
+```
+**不要把注释写在一行代码的前面或者代码的中间**
+
+### 2、必须添加的注释
+1. 除部分由其他脚本生成的脚本文件以外，在每个js文件的顶部必须有一个说明脚本功能的多行注释。多行注释至少需要说明清楚本脚本的大致功能和使用场合，并且要标注原始作者。
+  脚本功能注释例子如下：
+```js
+/**
+* 压缩解压模块
+* @author 陈昊
+*/
+```
+  在更旧的规范中，曾经要求在js文件顶部标注版本号。但是由于实际意义不大现在已经取消的这个要求
+
+2. 在每个函数之前，必须要有一个单行或者多行注释来说明函数的功能。如果函数比较复杂，则需要对参数和返回进行说明。
+  函数注释例子如下：
+```js
+//用gzip压缩目标对象或字符串
+function zip(raw) {
+  //这里是函数内容
+}
+```
+
+3. 所有非函数内局部变量都必须在声明之后加上注释。只要一个声明在一个函数之外，或者在多个函数中使用，就必须加上注释。**但是当该变量是对其他脚本的引用的时候，可以不加注释**
+  例如：
+```js
+  const _ = require('lodash'); //这个变量因为是对其他库和脚本的引用，可以不加注释
+  const curVersion = 1; //这个变量声明在某个函数之外并且在函数内被引用，必须添加注释
+  //检查版本是否和当前版本对应
+  function checkVerison(v) {
+    return v == curVersion;
+  }
+```
+
+### 3、建议添加的注释
+1. 函数内声明的变量，使用次数比较多或者是变量名不够一目了然的，建议添加注释来对变量进行说明（*下例中的1类注释*）
+2. 接下来的数行代码用于实现一个明确功能的，建议添加注释对该段代码逻辑进行说明（*下例中的2类注释*）
+3. 代码中某个地方需要注意的时候，建议添加注释进行提醒（*下例中的3类注释*）
+4. 对于某些复杂的逻辑判断，其他开发人员可能不能一眼看懂的，建议添加注释进行说明（*下例中的4类注释*）
+应用示例：
+```js
+  // 获取用户数据
+  async getRaw(guid) {
+    let keyGuid = `g:${guid}`; //GUID在redis里对应键值（1类注释）
+
+    let raw = await redis.get(keyGuid);
+    if (!raw) {
+      return null;
+    }
+    raw = JSON.parse(raw); // 写入redis的数据都是用JSON.stringify生成的，因此源数据必然是合法JSON（3类注释）
+
+    if (raw.userID < 0) { // 若数据已经失效，返回失败信息并删除原GUID数据（4类注释）
+      redis.del(keyGuid);
+      return raw;
+    }
+
+    // 检查用户数据版本并处理（2类注释）
+    if (raw.version == curVersion) {
+      redis.expire(keyGuid, timeLimit);
+      redis.expire(`u:${raw.userID}`, timeLimit);
+    } else if (raw.version > curVersion) {
+      throw new Error('用户数据版本高于当前服务器版本，请及时更新服务器');
+    } else {
+      raw = await this.createUserInfo(raw);
+      redis.setex(keyGuid, timeLimit, JSON.stringify(raw));
+    }
+    return raw;
+  };
+```
+
+### 4、不建议添加的注释
+1. 尽量不要在文件头部或者代码中添加文档级别的大量注释，如果确实需要进行大量的说明。可以单独编写文档，或者在文件底部专门编写大量说明用注释。
+2. 不要编写那些写了和没写一样的注释。
+  例如：
+```js
+  // 把数据库查到的数据处理成以key为键值的JSON并返回
+  function rows2json(rows, key = 'id'){
+    let json = {} // 待返回的JSON（由于该函数代码太短，这个变量的作用一眼就看出来了，因此这里的注释没有实际作用）
+
+    //处理数据，将其处理成以key为键值的JSON（几乎就是把函数功能复述了一遍，这个注释也没有意义）
+    for(let i=0; i<rows.length; i++) { // 遍历输入的数组（这种注释显然没有任何价值）
+      let cur = rows[i]; //当前数组对象（无论是从代码还是变量名都可以简单的知道这个变量是啥，该注释没有意义）
+      json[cur[key]] = cur; 
+    }
+
+    return json; //返回JSON（这种注释显然也没有意义）
+  }
+```
+3. 过于琐碎的注释。注释不能没有，也不宜太多，每隔个一两行就添加一个注释是完全不必要的。
+
+## 代码规范
+
 ## 版本管理规范
\ No newline at end of file