inula/CONTRIBUTING.md

1.1 KiB

代码注释

为提高代码的可读性,我们希望你能按照以下几条规则编写注释,

  • 核心:不要解释是什么,而是回答为什么

  • 统一的注释风格

      /**
      * 这是块级注释
      */
    
      // 这是行内注释
    
      //============================== 分隔符 ==============================
    
  • 注释不要重复代码内容

    // 注释和代码含义相同,无需添加
    // error是个promise
    if (isPromise(error)) {
      ...
    }
    
  • 注释不要解释模糊代码

    // 最佳节点
    let n: Node | null = null;
    

    直接在代码中通过名称表达清楚,可以省略掉注释

    let bestNode: Node | null = null;
    

    如果添加注释则是补充性的额外信息

    // 全局指针,在遍历时指向当前最佳的节点
    let bestNode: VNode | null = null;
    
  • 巧妙或复杂的代码要添加注释解释逻辑

  • 对所有导出的顶层模块进行注释

  • 注释应该是直接的,不要有不明确的表达或符号