前言：

?好的注释能提高代码的可读性和可维护性，从而提高代码质量。那么什么是好的注释？如何写出好的注释？

好的注释能提高代码的可读性和可维护性，从而提高代码质量。

那么什么是好的注释？如何写出好的注释？本文将从注释的目的和准则出发对 JS 注释进行讨论。

一、注释的目的和准则

注释的目的：

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

注释的准则：

如无必要，勿增注释 ( As short as possible )

如有必要，尽量详尽 (?As long as necessary )

「如无必要，勿增注释」是指注释要避免过多过滥，不要为了注释而注释。多余的注释等价于冗余的代码，除了对添加可读性无益，一旦代码需要修改，修改注释也会是一大负担。

我们应当追求「代码自注释」，即代码本身就拥有较高的可读性（通过清晰的命名、正当的结构等）。举个例子：

// bad // 假如已经准备好数据，就渲染表格 if (data.success && data.result.length > 0) { ?renderTable(data); ? } // good const isTableDataReady = data.success && data.result.length > 0; if (isTableDataReady) { ?renderTable(data); }

「如有必要，尽量详尽」是指需要注释的地方应该尽量详尽地去写，以让阅读者能充分理解代码的逻辑和用意为标准。

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

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

好的注释包括：

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

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

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

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

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

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

坏的注释包括：

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

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

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

小编推荐，前台学习交流群 330336289 ?邀请码：寂静！

三、如何写好注释

注释规约

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

工具保障

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

四、注释规约

这里给出一份可供参考的注释规约：

1.【推荐】单行注释用?//

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

// bad

const active = true; // is current tab

// good

// is current tab

const active = true;

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

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; }

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

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; ?} }

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：保证一致的注释风格

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

Sonar：检查项目的注释率

Sonar 是一个代码持续集成平台，它能对代码进行静态扫描，得到项目的注释率数据。

注释率反应了注释行占总代码行的比例，注释率太低不好，但也不可以盲目追求高注释率。

另外，同 Eslint 相似，Sonar 也有少量针对注释风格规则能配置。

后记

“Comment or not comment, that is the question”

了解注释的目的和准则，遵循一份注释规约并结合工具保证落地，能使注释成为代码良好的辅助，加强可读性和可维护性，从而提高代码质量。

?