前端注释规范

可以通过设置编辑器来设置出一致的注释模式。

1. HTML注释

• 模块注释

<!-- 订单详情模块 -->

• 区块注释

<!-- 
    @name: 订单详情
    @description: 主要是订单详情页面
    @author: fjw([email protected])
-->

2. CSS注释

• 组件块和子组件块以及声明块之间使用一空行分隔，子组件块之间三空行分隔；

/* ==========================================================================
组件块
============================================================================ */

/* 子组件块
============================================================================ */
.selector {
    padding: 15px;
    margin-bottom: 15px;
}

/* 子组件块
============================================================================ */
.selector-secondary {
    display: block; /* 注释*/
}

.selector-three {
    display: span;
}

3. JavaScript注释

• 单行注释：
  独占一行，后跟一个空格，缩进与下一行被注释说明的代码一致。

• 多行注释：
  避免使用 /.../ 这样的多行注释。有多行注释内容时，使用多个单行注释。

• 函数/方法注释：

  • 必须包含函数的说明；
  • 有参数和返回值时，必须有注释标志；
  • 参数和返回值必须包含类型信息和说明；
  • 当函数是内部函数，外部不可以访问时，可以使用@inner来标识；
  • 示范：

    /**
    * 函数描述
    *
    * @param {string} p1 参数1的说明
    * @param {string} p2 参数2的说明
    * @param {number=} p3 参数3的说明（可选）
    * @return {Object} 返回值描述
    */
    function foo(p1, p2, p3) {
        var p3 = p3 || 10;
        return {
            p1: p1,
            p2: p2,
            p3: p3
        };
    }
    

4. 文件注释

• 文件注释用于告诉不熟悉这段代码的读者这个文件中包含哪些东西。
• 文件注释要标明作者、文件版本、创建/修改时间、重大版本修改记录；
• 示范：

  /**
  * @fileoverview Description of file, its uses and information
  * about its dependencies.
  * @author [email protected] (Firstname Lastname)
  * Copyright 2019 QQ Inc. All Rights Reserved.
  */
  

!!! 以上规则仅供参考