注释那些事儿：前端代码质量系列文章(一)

“Comment or not comment, that is the question”

什么是好注释，什么是坏注释

根据注释的原则，我们应该以「能否帮助阅读者更好地阅读理解代码」为标准，判断一个注释「是否有必要」。

好的注释包括：

• 帮助读者更好地了解代码逻辑和结构，例如：

init: function() {

  // 获取配置信息

  const config = getConfig();

  

  // 获取用户信息

  const userInfo = getUserInfo();

  

  // 根据配置和用户信息，进行初始化

  doInit(config, userInfo);

  

  // 如果存在自定义配置时的特殊逻辑

  if (config.custom) {

    ...

  }

}

• 特殊或不易理解写法的解释说明，例如：

/** 

* parseInt was the reason my code was slow. 

* Bitshifting the String to coerce it to a 

* Number made it a lot faster. 

*/

const val = inputValue >> 0;

• 特殊标记注释：如 TODO、FIXME 等有特殊含义的标记
  

• 文件注释：部分规约会约定在文件头部书写固定格式的注释，如注明作者、协议等信息
  

• 文档类注释：部分规约会约定 API、类、函数等使用文档类注释（如 jsdoc 风格）

• 遵循统一的风格规范，如一定的空格、空行，以保证注释自身的可读性

坏的注释包括：

• 注释对阅读代码无益：如本文第一个示例，本可以不用注释，用清晰的命名、逻辑进行代码自注释

• 未遵循统一的风格规范：如单行注释长度、空格、空行，例如：

// bad 单行注释过长，不易阅读，应写成多行

// parseInt was the reason my code was slow.Bitshifting the String to coerce it to Number made it a lot faster.

const val = inputValue >> 0;



// good

/** 

* parseInt was the reason my code was slow. 

* Bitshifting the String to coerce it to a 

* Number made it a lot faster. 

*/

const val = inputValue >> 0;

• 情绪性注释：如抱怨、歧视、搞怪等（被发现你就跪了）

如何写好注释

注释规约

理解注释的目的和原则，制定并遵循一份注释规约，以保证注释的可读性和一致性

工具保障

比如使用 ESLint 保证注释风格的一致，使用 Sonar 检查项目注释率

04

—

4.1 【推荐】单行注释使用 //

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

// bad

const active = true; // is current tab



// good

// is current tab

const active = true;

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

// bad

function getType() {  

 console.log('fetching type...');  

 // set the default type to 'no type'
  const type = this.type || 'no type';  

 return type;
}

 

// good

function getType() {  

 console.log('fetching type...');  

 

 // set the default type to 'no type'
  const type = this.type || 'no type';  

 return type;
}



// good

// 注释行上面是一个块的顶部时不需要空行

function getType() {  

 // set the default type to 'no type'
  const type = this.type || 'no type';					
  return type;
}

4.2 【推荐】多行注释使用 /** ... */，而不是多行的 //

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

  return element;
}

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

  return element;
}

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

// bad

//is current tab

const active = true;



// good

// is current tab

const active = true;



// bad

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

function make(tag) {  

  // ...

  return element;
}



// good

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

function make(tag) {  

 // ...

  return element;
}

4.4 【推荐】使用特殊注释标记

有时我们发现某个可能的 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;
  }
}

4.5 【推荐】文档类注释，如函数、类、文件、事件等，使用 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;
  }
};

工具

我们可以使用一些工具来保证注释质量，例如：

Eslint：保证一致的注释风格

06

—