×
13518219792

建站动态

根据您的个性需求进行定制 先人一步 抢占小程序红利时代

编写高质量可维护的代码：一目了然的注释

 前言

有一些人认为，好的代码是自我解释的。合适的命名和优秀的代码的确可以减轻开发人员阅读代码的工作量，对于不是特别复杂的代码可能确实可以做到自我解释。但并不是所有场景都可以做到这一点，我们一起来了解一下“注释”吧。

编程语言中对“注释”的解释

注释就是对代码的解释和说明。注释是开发人员在编写程序时，给一段代码的解释或提示，有助于提高程序代码的可读性。注释不会被计算机编译。

要不要加注释？为什么要加注释？

注释的存在就是为了方便自己的二次阅读和代码维护以及项目交接。可以更好的理解代码，有助于提高协作效率，加快开发进程。

试想，你添加了一段逻辑较为复杂的代码，几个月后再看，还能不能迅速看懂？你刚刚接手一个老项目，项目里基本没有注释且逻辑复杂，你能高效率的看懂代码和了解业务吗？

所以添加注释还是有一定必要滴。

基础篇

快捷键 windows 系统： Ctrl+/ ios 系统： Command+/

注释的分类


  这是一行文字
  

 
 
 
 
    
  
  
  
  
    2. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. div {
    2. 
  
  
  
  
  2.     /* color: #fff;  */
    3. 
  
  
  
  
  3. }
    4. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. div {
    2. 
  
  
  
  
  2.     /* color: #fff;*/  /* 多行注释*/
    3. 
  
  
  
  
  3.     // font-size: 14px; // 单行注释
    4. 
  
  
  
  
  4.     background: #000;
    5. 
  
  
  
  
  5. }
    6. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. * 用注释来阻止代码执行  —— 被注释的 JS 代码将不被执行
    2. 
  
  
  
  
  2. 
  
  
  
  
  3. ```js
    4. 
  
  
  
  
  4. //alert("123")  // 执行时未弹出该信息
    5. 
  
  
  
  
  5. alert("456")  // 执行时弹出该信息
    6. 
  
  
  
  
  6. ```
    7. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. /**
    2. 
  
  
  
  
  2.  * 提交
    3. 
  
  
  
  
  3.  *
    4. 
  
  
  
  
  4.  * @method onSubmit
    5. 
  
  
  
  
  5.  * @param {[Object]} 提交数据
    6. 
  
  
  
  
  6.  * @return  {[Bollean]}  [返回是否提交成功 ]
    7. 
  
  
  
  
  7.  */
    8. 
  
  
  
  
  8. const onSubmit = (params = {}) => {
    9. 
  
  
  
  
  9.   const result = false;
    10. 
  
  
  
  
  10.     if (params) {
    11. 
  
  
  
  
  11.             result = true;
    12. 
  
  
  
  
  12.         }
    13. 
  
  
  
  
  13.     return result;
    14. 
  
  
  
  
  14. };
    15. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. // TODO功能未完成，待完善
    2. 
  
  
  
  
  2. // FIXME  待修复
    3. 
  
  
  
  
  3. // XXX    实现方法待确认
    4. 
  
  
  
  
  4. // NOTE   代码功能说明
    5. 
  
  
  
  
  5. // HACK   此处写法有待优化
    6. 
  
  
  
  
  6. // BUG    此处有Bug
    7. 
  
  
  
  
  7. const arr = []
    8.

Tips：

注释写法规范

 
 
 
 
    
  
  
  
  
  1. /*
    2. 
  
  
  
  
  2. * 简述当前文件功能
    3. 
  
  
  
  
  3. * @author 作者名称
    4. 
  
  
  
  
  4. * @version 版本号 最近编辑时间
    5. 
  
  
  
  
  5. * @description 该版本改动信息
    6. 
  
  
  
  
  6. */
    7. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. // 这是一行注释
    2. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. /*
    2. 
  
  
  
  
  2. 这里有一行注释
    3. 
  
  
  
  
  3. 这里有一行注释
    4. 
  
  
  
  
  4. 这里有一行注释
    5. 
  
  
  
  
  5. */
    6.

注释常用标签用法

/**

/**

 
 
 
 
    
  
  
  
  
  1. * @param {} name - some description
    2. 
  
  
  
  
  2.     * 非必传参数需给参数名加上'[]'
    3. 
  
  
  
  
  3.     * 参数如有默认值需用'='表示
    4. 
  
  
  
  
  4.     * 如果参数是object，可继续用`@param`对其属性进行详细说明
    5. 
  
  
  
  
  5.     * 若干个参数用`...`表示
    6. 
  
  
  
  
  6. ```javascript
    7. 
  
  
  
  
  7. /**
    8. 
  
  
  
  
  8.  * @func
    9. 
  
  
  
  
  9.  * @desc 一个带参数的函数
    10. 
  
  
  
  
  10.  * @param {string} a - 参数a
    11. 
  
  
  
  
  11.  * @param {number} b=1 - 参数b默认值为1
    12. 
  
  
  
  
  12.  * @param {string} c=1 - 参数c有两种支持的取值  1—表示x  2—表示xx
    13. 
  
  
  
  
  13.  * @param {object} d - 参数d为一个对象
    14. 
  
  
  
  
  14.  * @param {string} d.e - 参数d的e属性
    15. 
  
  
  
  
  15.  * @param {object[]} g - 参数g为一个对象数组
    16. 
  
  
  
  
  16.  * @param {string} g.h - 参数g数组中一项的h属性
    17. 
  
  
  
  
  17.  * @param {string} [j] - 参数j是一个可选参数
    18. 
  
  
  
  
  18.  */
    19. 
  
  
  
  
  19.  function foo(a, b, c, d, g, j) {}
    20. 
  
  
  
  
  20. 
  
  
  
  
  21. /**
    22. 
  
  
  
  
  22.  * @func
    23. 
  
  
  
  
  23.  * @desc 一个带若干参数的函数
    24. 
  
  
  
  
  24.  * @param {...string} a - 参数a
    25. 
  
  
  
  
  25.  */
    26. 
  
  
  
  
  26. function bar(a) {}
    27.

了解更多可查看 JSDoc

拓展篇

IE 条件注释（IE5+）

IE 条件注释分为以下几种情况：

 
 
 
 
    
  
  
  
  
  1. 
  
  
  
  
  2.     IE 条件注释
    3. 
  
  
  
  
  3. 
  
  
  
  
  4.     
    5. 
  
  
  
  
  5.   
    6. 
  
  
  
  
  6. 
  
  
  
  
  7.   
    8. 
  
  
  
  
  8.         
    9. 
  
  
  
  
  9. 
  
  
  
  
  10.   
    11. 
  
  
  
  
  11.     
    12. 
  
  
  
  
  12. 
  
  
  
  
  13.     
    14. 
  
  
  
  
  14.     
    15. 
  
  
  
  
  15. 
  
  
  
  
  16.     
    17. 
  
  
  
  
  17.      
    18. 
  
  
  
  
  18.

# （井号）注释 和 ''' （三引号）注释

 
 
 
 
    
  
  
  
  
  1. # python 的单行注释一
    2. 
  
  
  
  
  2.   print("I could have code like this.") # python 的单行注释二
    3.

print("This won't run.") # 被注释的代码

''' 被三引号包裹的段落 可以随意折行 也可以注释代码 print("This won't run.") '''

 
 
 
 
    
  
  
  
  
  1. #### 注释“被执行”了？
    2. 
  
  
  
  
  2. 
  
  
  
  
  3. 众所周知，注释的代码是不会被执行的。但是小编在查资料时看到了一段比较有意思的代码， Java 中的一行注释“被执行”了？
    4. 
  
  
  
  
  4. 
  
  
  
  
  5. 
  
  
  
  
  6. ```java
    7. 
  
  
  
  
  7. public class Test {
    8. 
  
  
  
  
  8.     public static void main(String[] args) {
    9. 
  
  
  
  
  9.         String name = "赵大";
    10. 
  
  
  
  
  10.         // \u000dname="钱二";
    11. 
  
  
  
  
  11.         System.out.println(name);
    12. 
  
  
  
  
  12.     }
    13. 
  
  
  
  
  13. }
    14.

这段代码执行后的结果为 钱二 ，也就是说在这段代码中，“被注释”的那行代码生效了！

这段代码的问题出在 \u000d 这串特殊字符上。 \u000d 是一串 Unicode 字符，代表换行符。Java 编译器不仅会编译代码，还会解析 Unicode 字符。在上面这段代码把 \u000d 给解析了，后面的代码就到了下面一行，超出了被注释的范围（单行注释的注释范围仅在当前行），所以执行结果为 钱二 而非 赵大 。（如下）

 
 
 
 
    
  
  
  
  
  1. public class Test {
    2. 
  
  
  
  
  2.     public static void main(String[] args) {
    3. 
  
  
  
  
  3.         String name = "赵大";
    4. 
  
  
  
  
  4.         //
    5. 
  
  
  
  
  5.         name="钱二";
    6. 
  
  
  
  
  6.         System.out.println(name);
    7. 
  
  
  
  
  7.     }
    8. 
  
  
  
  
  8. }
    9.

​ 所以本质上在代码执行的时候 name="钱二" 并没有被注释，而是被换了行（奇怪的知识增加了）。 所以切记，注释确实是不会被执行的哦！

注释相关插件

​ 在这里推荐几个个人认为比较好用的注释相关的Vscode插件，可在 setting.json 文件下自定义设置（可通过 '文件—选择项—设置'，打开 Vscode 文件 settings.json ）

用事实说话

口说无凭，眼见为实。下面我们看下实际开发中的具体情况：

 
 
 
 
    
  
  
  
  
  1. const noWarehousetemIds = beSelectSkucontainer.reduce((arr, itemId) => {
    2. 
  
  
  
  
  2.   const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
    3. 
  
  
  
  
  3.     const sku = selectRowskey[itemId][skuId];
    4. 
  
  
  
  
  4.     return !!sku.warehouseCode || lodashGet(warehouses, '[0].code');
    5. 
  
  
  
  
  5.   });
    6. 
  
  
  
  
  6.   if (!res) {
    7. 
  
  
  
  
  7.     arr.push(itemId);
    8. 
  
  
  
  
  8.   }
    9. 
  
  
  
  
  9.   return arr;
    10. 
  
  
  
  
  10. }, []);
    11. 
  
  
  
  
  11. if (noWarehousetemIds.length > 0 || noStockItemIds.length > 0) {
    12. 
  
  
  
  
  12.   const itemIds = Array.from(new Set([...noWarehousetemIds, ...noStockItemIds]));
    13. 
  
  
  
  
  13.   const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
    14. 
  
  
  
  
  14.   return Modal.warning({
    15. 
  
  
  
  
  15.     title: '错误提示',
    16. 
  
  
  
  
  16.     content: `“${itemNames.join(',')}”库存信息未完善，请完善库存信息`,
    17. 
  
  
  
  
  17.   });
    18. 
  
  
  
  
  18. }
    19. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. // 遍历当前所有选中的sku，查找出没有库存的itemId
    2. 
  
  
  
  
  2. const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
    3. 
  
  
  
  
  3. const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
    4. 
  
  
  
  
  4.   const sku = selectRowskey[itemId][skuId];
    5. 
  
  
  
  
  5.   return !!sku.stockQuantity;
    6. 
  
  
  
  
  6. });
    7. 
  
  
  
  
  7. if (!res) {
    8. 
  
  
  
  
  8.   arr.push(itemId);
    9. 
  
  
  
  
  9. }
    10. 
  
  
  
  
  10. return arr;
    11. 
  
  
  
  
  11. }, []);
    12. 
  
  
  
  
  12. // 有一条sku的库存为空时进入校验
    13. 
  
  
  
  
  13. if (noStockItemIds.length > 0) {
    14. 
  
  
  
  
  14. const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
    15. 
  
  
  
  
  15. return Modal.warning({
    16. 
  
  
  
  
  16.   title: '错误提示',
    17. 
  
  
  
  
  17.   content: `“${itemNames.join(',')}”库存信息未完善，请完善库存信息`,
    18. 
  
  
  
  
  18. });
    19. 
  
  
  
  
  19. }
    20. 
 
 
 
 
 
 
 
 
    
  
  
  
  
  1. // 遍历当前所有选中的sku，查找出没有库存的itemId
    2. 
  
  
  
  
  2. const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => {
    3. 
  
  
  
  
  3.   // selectRowskey是一个对象，以itemId为key，sku对象作为value，sku对象以skuId作为key，sku作为value，只有selectRowskey下所有itemId下的sku都有库存才算校验通过
    4. 
  
  
  
  
  4.   /*
    5. 
  
  
  
  
  5.       数据格式:
    6. 
  
  
  
  
  6.       selectRowskey: {
    7. 
  
  
  
  
  7.         12345678: { // itemId
    8. 
  
  
  
  
  8.             123456: { // skuId
    9. 
  
  
  
  
  9.             name: 'sku',
    10. 
  
  
  
  
  10.             }
    11. 
  
  
  
  
  11.         }
    12. 
  
  
  
  
  12.       }
    13. 
  
  
  
  
  13.     */
    14. 
  
  
  
  
  14.   const res = Object.keys(selectRowskey[itemId]).every((skuId) => {
    15. 
  
  
  
  
  15.       const sku = selectRowskey[itemId][skuId];
    16. 
  
  
  
  
  16.       return !!sku.stockQuantity;
    17. 
  
  
  
  
  17.   });
    18. 
  
  
  
  
  18.   // 只要有一条sku没有库存时，就塞到arr中，返回给noStockItemIds数组
    19. 
  
  
  
  
  19.   if (!res) {
    20. 
  
  
  
  
  20.       arr.push(itemId);
    21. 
  
  
  
  
  21.   }
    22. 
  
  
  
  
  22.   return arr;
    23. 
  
  
  
  
  23. }, []);
    24. 
  
  
  
  
  24. // 有一条sku的库存为空时进入校验
    25. 
  
  
  
  
  25. if (noStockItemIds.length > 0) {
    26. 
  
  
  
  
  26.   // 根据id查找商品名称
    27. 
  
  
  
  
  27.   const itemNames = itemIds.map(i => this.itemNameMap[i].itemName);
    28. 
  
  
  
  
  28.   Modal.warning({
    29. 
  
  
  
  
  29.       title: '错误提示',
    30. 
  
  
  
  
  30.       content: `“${itemNames.join(',')}”库存信息未完善，请完善库存信息`,
    31. 
  
  
  
  
  31.   });
    32. 
  
  
  
  
  32. }
    33.

看到上面这段代码可以很明显的体会到有没有注释以及注释写的清不清楚的重要性。若是写了注释但仍然看不懂，那还不如不写。

所以注释也不是随便写一写就可以的，要描述某段代码的功能，注明逻辑，让开发者可以”无脑“浏览。

之前在工作群中看到有人发过这样一张图（如下图），个人认为是一个很好的代码注释的范例：

结语

看到这里，对于注释的重要性各位已经有自己的认知。还有几点是我们写注释时需要注意的：


名称栏目：编写高质量可维护的代码：一目了然的注释
新闻来源：http://cdbrznjsb.com/article/djgcodd.html

其他资讯

让你的专属顾问为你服务