注释规范-前端开发

IT小镇做题家
158 阅读9分钟

注释规范

快速阅读友情提示：你可以通过右侧的目录索引快速跳转到你想要阅读的内容

为什么要注释

 简而言之，就是给以后需要用到你代码的人，或者需要理解你的代码的人(这个人或许就是你自己)留下有用的、方便看懂的信息。

注释的基本要求

 注释应该和它们所注释的代 码一样是书写良好且清晰明了。 避免冗长或者情绪化的注释。比如SB等字样

需要注释的模块

一、HTML

二、CSS

三、JAVASCRIPT

具体的书写规范

通过参考阿里、腾讯、京东等多家公司的注释规范以及W3C的注释标准并结合我们集团的现状，针对以上三个模块制定如下的规则草稿：

一、HTML注释

参考W3C的注释标准和几家主流公司的规范，可以概括为以下几点要求：

  • 必须以4个有序字符开始：编码为 U+003C LESS-THAN SIGN 的小于号, 编码为 U+0021 EXCLAMATION MARK 的感叹号, 编码为 U+002D HYPHEN-MINUS 横线, 编码为 U+002D HYPHEN-MINUS横线 ，即 <!--
  • 在此之后是注释内容，注释的内容有以下限制：
  1、不能以单个 “>” (U+003E) 字符开始
  2、不能以由 “-“（U+002D HYPHEN-MINUS）和 ”>” (U+003E) 组合的字符开始，即 “->”
  3、不能包含两个连续的 U+002D HYPHEN-MINUS 字符，即 “--”
  4、不能以一个 U+002D HYPHEN-MINUS 字符结束，即 “-”
  • 必须以3个有序字符结束：U+002D HYPHEN-MINUS, U+002D HYPHEN-MINUS, U+003E GREATER-THAN SIGN，即 -->
   W3C的标准写法：
   <!-- login模块 -->	
   <div class="login">
       ...
   </div>

   错误的用法:
   <!-->The Wrong Comment Text-->
   <!--->The Wrong Comment Text-->
   <!--The--Wrong--Comment Text-->
   <!--The Wrong Comment Text--->

公司团队层面的注释约定

  1. 单行注释，一般用于简单的描述，如某些状态描述、属性描述等。注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行
  2. 主要模块注释，一般用于描述模块的名称以及模块开始与结束的位置
  3. 嵌套模块注释，当一个主模块嵌套了其他子模块时，就需要使用嵌套模块注释

团队注释约定的详细说明

一、单行注释

# 作用
一般用于简单的描述，如某些状态描述、属性描述等。注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行

# 推荐用法
<!-- Comment Text -->
<div>...</div>

# 不推荐用法
<div>...</div><!-- Comment Text -->	
	
<div><!-- Comment Text -->
    ...
</div>

二、主要模块注释

# 作用
一般用于描述模块的名称以及模块开始与结束的位置
注释内容前后各一个空格字符，<!-- S Comment Text --> 表示模块开始，<!-- E Comment Text --> 表示模块结束，模块与模块之间相隔一行

# 推荐用法
<!-- S Comment Text A -->	
<div class="mod_a">
    ...
</div>
<!-- E Comment Text A -->
	
<!-- S Comment Text B -->	
<div class="mod_b">
    ...
</div>
<!-- E Comment Text B -->

# 不推荐用法
<!-- E Comment Text A -->
<div class="mod_a">
    ...
</div>
<!-- S Comment Text A -->
<!-- S Comment Text B -->	
<div class="mod_b">
    ...
</div>
<!-- E Comment Text B -->

三、嵌套模块注释

# 作用
当一个主模块嵌套了其他子模块时，就需要使用嵌套模块注释，为了突出主要模块，嵌套模块不再使用<!-- S Comment Text --> 、 <!-- E Comment Text -->的形式，而是改用单行<!-- /Comment Text --> 的形式 

# 使用示例
<!-- S Comment Text A -->
<div class="mod_a">
    <div class="mod_b">
        ...
    </div>
    <!-- /mod_b -->
    	
    <div class="mod_c">
    	...
    </div>
    <!-- /mod_c -->
</div>
<!-- E Comment Text A -->

二、CSS注释

注释要求

参考W3C的注释标准和几家主流公司的规范，可以概括为以下几点要求：

  • 注释以字符 /* 开始，以字符 */ 结束
  • 注释不能嵌套
  • 公司团队另行约定的注释规范

W3C的标准写法

/* Comment Text */
.test{}

公司团队层面的注释约定

  1. 文件头注释
  2. 单行注释
  3. 模块注释

团队注释约定的详细说明

一、文件头注释

# 作用
记录文件的基础信息，一般写在文件顶部位置

# 用法示例
/**
 * @desc Style for module header
 * @author Author Name
 * @date 2022-06-22
 */

二、单行注释

# 作用和要求
主要针对一些有特殊含义的样式，或者一些奇葩点的hack要加单行注释，方便理解和记忆。
一般注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行。

# 推荐用法
/* Comment Text */
.header{}

# 不推荐用法
/*Comment Text*/
.jdc{
	display: block;
}
.jdc{
	display: block;/*Comment Text*/
}

三、嵌套模块注释

# 作用和要求
主要针对HTML中具有鲜明结构模块的这些样式进行模块注释，比如弹窗、轮播图等等。
注释内容第一个字符和最后一个字符都是一个空格字符，/* 与 模块信息描述占一行，多个横线分隔符-与*/占一行，行与行之间相隔两行

# 推荐用法
/* Module A
---------------------------------------------------------------- */
.mod_a {}

/* Module B
---------------------------------------------------------------- */
.mod_b {}

# 不推荐用法
/* Module A ---------------------------------------------------- */
.mod_a {}
/* Module B ---------------------------------------------------- */
.mod_b {}

三、JAVASCRIPT注释

背景

由于前端技术很大一部分价值都体现在JS上，所以JS注释在前端三大模中最具分量、作用最大，同时也是最复杂的。从长远角度来说，JS的注释并不仅仅是注释，他应该跟代码一样不停的被迭代和维护，并生成一套可视化的文档，以方便开发查阅。而想要达到这个效果，我们的注释就需要遵守一套规则，我们可以通过这套规则去匹配相关的内容，从而生成相对应的接口文档，但是这个工作量是非常大的，可能需要一个团队花一定的时间去开发和维护，这个投入和产出其实并不对等。所以我们需要一个能够根据我们的注释信息，生成模块或者库API文档的工具。这边我参考了目前市面上比较流行的注释库，以及阿里、腾讯、京东等主流大厂的技术开发社区和项目，并结合目前我们三家公司的技术栈，最后选出了一个JS注释库，JSDoc。

为什么选择JSDoc

1、开源
2、一键生成API文档网站，类似JavaDoc和PHPDoc
3、结合考虑目前我们三家公司的使用现状，目前我们三家公司都有使用JSDoc的经验，方便入手和使用
4、方便进行功能拓展，jsdoc提供了插件接口，我们可以通过插件接口自行编写一套注释和文档生成的规则
5、ide插件支持，目前很多ide都支持jsdoc，比如vscode和webstorm，这可以帮助我们更便捷的添加注释，从而提高我们的开发效率
6、阿里、华为、腾讯等公司在技术社区或者他们的实际项目中都推荐的一种注释工具

具体注释规则

我们在进行JS注释时需要遵循JSDoc的注释规则，下面我以JSDoc3的注释规则为例，列举几个我们开发中比较常见的注释规则(特殊注释需求不在通用规则中)：
一、基础要求

  • 注释可以分为单行和多行注释。单行注释一般使用双斜杠，后面留一个空格；多行注释一般以/**开头，以*/结尾，开头和结尾单独成行，示例如下:
   // 单行注释，一般用于单行代码的说明

   /**
     * 多行注释，一般用于整个函数或者业务模块的说明
     */
  • 所有js文件头部, 必须有文件注释, 用于简要说明: 文件的主要功能(含模块信息)、作者、版权等信息。 文件头注释格式如下:
   /**
     * @description class description //@description在第一行时可省略
     * @author test
     * @module local/test
     * @license MIT //许可协议，如果需要则加上，
     */
    class test {
      ...
    });
  • 注释需要简洁明了, 只与代码相关
  • 及时地更新注释, 错误的注释会让程序更加难以阅读和理解
  • (建议) 公用模块方法，请使用@example添加范例代码，示例如下：
  /**
    * Solves equations of the form a * x = b
    * @example
    * global.method1(5, 10);
    * @returns {number} Returns the value of x for the equation.
    */
    global.method = function (a, b) {
        return b / a;
    };
  • (建议) 所有的注释请尽量使用英文(方便跨平台编辑)
  • 注释没有必要每行都添加, 只在重要的逻辑、或者较复杂的逻辑处, 增加必要的注释
  • 每个对外暴露的 API 方法, 需要加注释说明其用途。注释需要包括: 函数的用途、参数、返回值等, 此三项为强制要求，示例如下：
   /**
     * Addition function
     * @method add
     * @param {number} num1 addend
     * @param {number} num2 summand
     * @returns {number} Returns the sum of two numbers
     */
    function add(num1, num2) {
	return num1 + num2
    }
  • 重要的变量声明须添加注释, 说明变量用途，示例如下：
   /**
     * defined userInfo for local test
     * @namespace
     * @constant {object}
     * @property {string} name            - The name of user
     * @property {number} age             - The age of user
     * @property {arrary} interest        - The interest of user
     * @property {object} shoes           - The shoes info of user
     * @property {string} shoes.color     - The color of shoes
     */
    const userInfo = {
	name: 'test',
	age: 18,
	interest: ['book','movie'],
	shoes: {
		color: 'red'
	}
    }

   /**
     * Enum for http code.
     * @readonly
     * @enum {number}
     */
    const httpCode = {
        SUCCESS: 200,
        FAIL: 400,
        REDIRECT: 302
    };

二、其他注释要求

  • 类方法注释示例：
  /**
     * This is a description of the Person function
     * @class
     * @param {string} name  - the name of user
     * @param {number} age   - the age of user
     */
     class Person {
	  constructor(name,age){
	  this.name = name;
          this.age = age;
      }
     Say(){
         return '我的名字是' + this.name;
     }
   }
 
   var p = new Person('myname', 18);
  • 代办注释，示例如下：
   /**
     * This is a description of the task function
     * @todo Incompatible with lower version clients
     * @function
     */
    function task() {
       // write something
    }
  • 自定义类型的复用，示例如下：
   /**
     * A basic application of typedef.
     * @typedef {(number|string|object|array)} test
     */
   /**
     * local test for type reuse
     * @param {test} params - use custom type.
     */
    function localtest(params) {
    }

三、常用标签说明

标签含义
@author指定项目的作者
@desc @description对代码的描述和说明
@extends @augments指明继承自哪个父类，后面需要加父类名
@arg @argument @param对函数入参的类型说明和描述
@constructor指明当前函数将用来作为类的构造函数
@copyright描述一些版权信息
@enum对一个静态属性集合的描述，通常和@readonly结合使用
@readonly标记为只读
@todo记录一个待完成的任务
@property描述一个对象的属性

更多标签的含义和使用说明请查阅JSDoc官方文档

四、TYPESCRIPT注释

枚举

枚举对象本身和枚举成员都使用 PascalCase 方式命名。

// Bad
enum status {}

// Good
enum Status {}

**

avatar
文章
阅读
粉丝