前言：
好的註釋可以提高程式碼的可讀性和可維護性，從而提高程式碼質量。那麼什麼是好的註釋？如何寫出好的註釋？ 好的註釋可以提高程式碼的可讀性和可維護性，從而提高程式碼質量。
那麼什麼是好的註釋？如何寫出好的註釋？本文將從註釋的目的和原則出發對 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); } 「如有必要，儘量詳盡」是指需要註釋的地方應該儘量詳盡地去寫，以讓閱讀者可以充分了解程式碼的邏輯和意圖為標準。
二、什麼是好註釋，什麼是壞註釋
根據註釋的原則，我們應該以「能否幫助閱讀者更好地閱讀理解程式碼」為標準，判斷一個註釋「是否有必要」。
好的註釋包括：
幫助讀者更好地瞭解程式碼邏輯和結構，例如：
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;
情緒性註釋：如抱怨、歧視、搞怪等（被發現你就跪了）
做為一名前端程式設計師，有一個學習的氛圍跟一個交流圈子特別重要。這是我的一個前端學習交流群 330336289（邀請碼：寂靜），想學習交流前端，打算深入瞭解這個行業的朋友，不管你是小白還是大牛都歡迎加入，大家一起交流學習。
三、如何寫好註釋
註釋規約
理解註釋的目的和原則，制定並遵循一份註釋規約，以保證註釋的可讀性和一致性
工具保障
比如使用 ESLint 保證註釋風格的一致，使用 Sonar 檢查專案註釋率
四、註釋規約
這裡給出一份可供參考的註釋規約：
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; }
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
pgc-image/152531852952604e64de90b
請點選此處輸入圖片描述
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”
理解註釋的目的和原則，遵循一份註釋規約並結合工具保證落地，可以使註釋成為程式碼良好的輔助，增強可讀性和可維護性，從而提高程式碼質量。