注释规范

# 注释规范

注释的目的：

提高代码的可读性，从而提高代码的可维护性

注释的原则：

如无必要，勿增注释 ( As short as possible )
如有必要，尽量详尽 ( As long as necessary )

# HTML 文件注释

# 单行注释

一般用于简单的描述，如某些状态描述、属性描述等。

注释内容前后各一个空格字符，注释位于要注释代码的上面，单独占一行。

推荐：

<!-- Comment Text -->
<div>...</div>

1
2

不推荐：

<div>...</div><!-- Comment Text -->

<div><!-- Comment Text -->
  ...
</div>

1
2
3
4
5

# 模块注释

一般用于描述模块的名称以及模块开始与结束的位置。

注释内容前后各一个空格字符，  表示模块开始，  表示模块结束，模块与模块之间相隔一行。

推荐：

<!-- 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 -->

1
2
3
4
5
6
7
8
9
10
11

不推荐：

<!-- 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 -->

1
2
3
4
5
6
7
8
9
10

# 嵌套模块注释

当模块注释内再出现模块注释的时候，为了突出主要模块，嵌套模块不再使用。

<!-- S Comment Text -->
<!-- E Comment Text -->

1
2

而改用

<!-- /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 -->

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# CSS 文件注释

# 单行注释

注释内容第一个字符和最后一个字符都是一个空格字符，单独占一行，行与行之间相隔一行。

推荐：

/* Comment Text */ 
.jdc {} 

/* Comment Text */ 
.jdc {}

1
2
3
4
5

不推荐：

/*Comment Text*/
.jdc {
  display: block;
}

.jdc {
  display: block;/*Comment Text*/
}

1
2
3
4
5
6
7
8

# 模块注释

注释内容第一个字符和最后一个字符都是一个空格字符，/* 与模块信息描述占一行，多个横线分隔符 - 与 */ 占一行，行与行之间相隔两行。

推荐：

/* Module A
---------------------------------------------------------------- */
.mod_a {}


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

1
2
3
4
5
6
7
8

不推荐：

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

1
2
3
4

# 文件注释

在样式文件编码声明 @charset 语句下面注明页面名称、作者、创建日期等信息。

@charset "UTF-8";
/**
 * @desc File Info
 * @author Author Name
 * @date 2015-10-10
 */

1
2
3
4
5
6

# JavaScript 文件注释

# 单行注释

单行注释使用 //，注释应单独一行写在被注释对象的上方，不要追加在某条语句的后面。

推荐：

// is current tab
const active = true

1
2

不推荐：

const active = true // is current tab

注释行的上方需要有一个空行（除非注释行上方是一个块的顶部），以增加可读性。

推荐：

function getType () {  
  console.log('fetching type...')
  
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}

1
2
3
4
5
6
7

// 注释行上面是一个块的顶部时不需要空行
function getType () {  
  // set the default type to 'no type'
  const type = this.type || 'no type'			
  return type
}

1
2
3
4
5
6

不推荐：

function getType () {  
  console.log('fetching type...')
  // set the default type to 'no type'
  const type = this.type || 'no type'
  return type
}

1
2
3
4
5
6

# 多行注释

多行注释使用 /** ... */，而不是多行的 //。

推荐：

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make (tag) {
  // ...

  return element
}

1
2
3
4
5
6
7
8
9

不推荐：

// make() returns a new element
// based on the passed in tag name
function make (tag) {
  // ...

  return element
}

1
2
3
4
5
6
7

# 注释空格

注释内容和注释符之间需要有一个空格，以增加可读性。eslint: spaced-comment。

推荐：

// is current tab
const active = true

/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}

1
2
3
4
5
6
7
8
9
10
11
12

不推荐：

//is current tab
const active = true

/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {  
  // ...

  return element
}

1
2
3
4
5
6
7
8
9
10
11
12

# 特殊标记

有时我们发现某个可能的 bug，但因为一些原因还没法修复；或者某个地方还有一些待完成的功能，这时我们需要使用相应的特殊标记注释来告知未来的自己或合作者。常用的特殊标记有两种：

// FIXME : 说明问题是什么
// TODO : 说明还要做什么或者问题的解决方案

class Calculator extends Abacus {
  constructor () {
    super ()

      // FIXME: shouldn’t use a global here
      total = 0

      // TODO: total should be configurable by an options param
      this.total = 0
  }
}

1
2
3
4
5
6
7
8
9
10
11

# 文档类注释

文档类注释，如函数、类、文件、事件等；都使用 jsdoc 规范。

/**
 * Book类，代表一个书本.
 * @constructor
 * @param {string} title - 书本的标题.
 * @param {string} author - 书本的作者.
 */
function Book (title, author) {
  this.title = title
  this.author = author
}

Book.prototype = {
  /**
   * 获取书本的标题
   * @returns {string|*}
   */
  getTitle: function () {
    return this.title
  },
  /**
   * 设置书本的页数
   * @param pageNum {number} 页数
   */
  setPageNum: function (pageNum) {
    this.pageNum=pageNum
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 注释工具

ESLint 是当下最流行的 JS 代码检查工具，ESLint 中有一些注释相关的规则，用户可选择开启：

valid-jsdoc
require-jsdoc
no-warning-comments
capitalized-comments
line-comment-position
lines-around-comment
multiline-comment-style
no-inline-comments
spaced-comment

编辑

上次更新: 2021/08/10, 05:44:53

← 代码规范 new命令原理→