摘要：?好的注釋可以提高代碼的可讀性和可維護性，從而提高代碼質量。那么什么是好的注釋？如何寫出好的注釋？

“Comment or not comment, that is the question”

好的注釋可以提高代碼的可讀性和可維護性，從而提高代碼質量。

那么什么是好的注釋？如何寫出好的注釋？本文將從注釋的目的和原則出發對 JS 注釋進行探討。

01

—

注釋的目的和原則

注釋的目的：

• 提高代碼的可讀性，從而提高代碼的可維護性

注釋的原則：

• 如無必要，勿增注釋 ( As short as possible )

• 如有必要，盡量詳盡 (?As long as necessary )

我們寫注釋，是為了給代碼的讀者（包括我們自己，也可能包括機器，如 jsdoc）看，幫助讀者閱讀理解代碼并進行維護。
「如無必要，勿增注釋」是指注釋要避免過多過濫，不要為了注釋而注釋。多余的注釋等價于冗余的代碼，除了對增加可讀性無益，一旦代碼需要修改，修改注釋也會是一大負擔。

我們應當追求「代碼自注釋」，即代碼本身就擁有較高的可讀性（通過清晰的命名、合理的結構等）。舉個例子：

// bad // 如果已經準備好數據，就渲染表格 if (data.success && data.result.length > 0) {renderTable(data); ? }// good const isTableDataReady = data.success && data.result.length > 0; if (isTableDataReady) {renderTable(data); }

「如有必要，盡量詳盡」是指需要注釋的地方應該盡量詳盡地去寫，以讓閱讀者可以充分了解代碼的邏輯和意圖為標準。

02

—

什么是好注釋，什么是壞注釋

根據注釋的原則，我們應該以「能否幫助閱讀者更好地閱讀理解代碼」為標準，判斷一個注釋「是否有必要」。

好的注釋包括：

• 幫助讀者更好地了解代碼邏輯和結構，例如：

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;

• 情緒性注釋：如抱怨、歧視、搞怪等（被發現你就跪了）

03

—

如何寫好注釋

注釋規約

理解注釋的目的和原則，制定并遵循一份注釋規約，以保證注釋的可讀性和一致性

工具保障

比如使用 ESLint 保證注釋風格的一致，使用 Sonar 檢查項目注釋率

04

—

注釋規約

這里給出一份可供參考的注釋規約（參考自airbnb規約）：

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 heretotal = 0;// TODO: total should be configurable by an options paramthis.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;} };

05

—

工具

我們可以使用一些工具來保證注釋質量，例如：

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 也有一些針對注釋風格規則可以配置。

06

—

后記

理解注釋的目的和原則，遵循一份注釋規約并結合工具保證落地，可以使注釋成為代碼良好的輔助，增強可讀性和可維護性，從而提高代碼質量。

本篇是《前端代碼質量系列文章》的第一篇，后續系列文章還將討論編碼規約、復雜度、重復率等主題，敬請期待：）

本文部分內容和代碼示例參考：

• aralejs注釋規范?https://github.com/aralejs/aralejs.github.io/wiki/JavaScript-注釋規范

• airbnb編碼規約?https://github.com/airbnb/javascript#comments
  

• http://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/

原文鏈接

本文為云棲社區原創內容，未經允許不得轉載。

總結

以上是生活随笔為你收集整理的注释那些事儿：前端代码质量系列文章(一)的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。