前言

有一些人認(rèn)為，好的代碼是自我解釋的。合適的命名和優(yōu)秀的代碼的確可以減輕開發(fā)人員閱讀代碼的工作量，對于不是特別復(fù)雜的代碼可能確實(shí)可以做到自我解釋。但并不是所有場景都可以做到這一點(diǎn)，我們一起來了解一下“注釋”吧。

編程語言中對“注釋”的解釋

注釋就是對代碼的解釋和說明。注釋是開發(fā)人員在編寫程序時(shí)，給一段代碼的解釋或提示，有助于提高程序代碼的可讀性。注釋不會被計(jì)算機(jī)編譯。

[[344072]]

要不要加注釋？為什么要加注釋？

注釋的存在就是為了方便自己的二次閱讀和代碼維護(hù)以及項(xiàng)目交接。可以更好的理解代碼，有助于提高協(xié)作效率，加快開發(fā)進(jìn)程。

試想，你添加了一段邏輯較為復(fù)雜的代碼，幾個月后再看，還能不能迅速看懂？你剛剛接手一個老項(xiàng)目，項(xiàng)目里基本沒有注釋且邏輯復(fù)雜，你能高效率的看懂代碼和了解業(yè)務(wù)嗎？

所以添加注釋還是有一定必要滴。

基礎(chǔ)篇

快捷鍵 windows 系統(tǒng)： Ctrl+/ ios 系統(tǒng)： Command+/

注釋的分類

• HTML中的注釋

<div>
  這是一行文字
  <!-- 這是一行被注釋的文字 -->
</div>

• CSS 中的注釋

<style> 
  div { 
      /* color: #fff;  */ 
   } 
</style> 

div { 
    /* color: #fff;  */ 
} 

div { 
    /* color: #fff;*/  /* 多行注釋*/ 
    // font-size: 14px; // 單行注釋 
    background: #000; 
} 

• 在 HTML 中
• 在 .css文件中
• 在 .less 或 .scss 文件中

• JS 中的注釋

  • 用法

    • 可用于解釋 JavaScript 代碼，增強(qiáng)其可讀性。
    • 也可以用于阻止代碼執(zhí)行。

  • 單行注釋（行注釋）—— 以 // 開頭。任何位于 // 之后的文本都會被注釋

• 多行注釋（塊注釋）——以 /* 開頭，以 */ 結(jié)尾。任何位于 /* 和 */ 之間的文本都會被注釋

/* 
  這是多行注釋 
  定義一個數(shù)組 
*/ 
var ary = []; 

* 用注釋來阻止代碼執(zhí)行  —— 被注釋的 JS 代碼將不被執(zhí)行 
 
```js 
//alert("123")  // 執(zhí)行時(shí)未彈出該信息 
alert("456")  // 執(zhí)行時(shí)彈出該信息 
``` 

• 函數(shù)注釋

  • 一般以 /** 開頭，以 */ 結(jié)尾。任何位于 /** 和 */ 之間的文本都會被注釋

/** 
 * 提交 
 * 
 * @method onSubmit 
 * @param {[Object]} 提交數(shù)據(jù) 
 * @return  {[Bollean]}  [返回是否提交成功 ] 
 */ 
const onSubmit = (params = {}) => { 
  const result = false; 
    if (params) { 
            result = true; 
        } 
    return result; 
}; 

• 特殊標(biāo)記注釋
  • TODO 在該注釋處有功能代碼待編寫，待實(shí)現(xiàn)的功能在說明中會簡略說明
  • FIXME 在該注釋處代碼需要修正，甚至代碼是錯誤的，不能工作，需要修復(fù)，如何修正會在說明中簡略說明
  • XXX 在該注釋處代碼雖然實(shí)現(xiàn)了功能，但是實(shí)現(xiàn)的方法有待商榷，希望將來能改進(jìn)，要改進(jìn)的地方會在說明中簡略說明
  • NOTE 在該注釋處說明代碼如何工作
  • HACK 在該注釋處編寫得不好或格式錯誤，需要根據(jù)自己的需求去調(diào)整程序代碼
  • BUG 在該注釋處有 Bug

// TODO功能未完成，待完善 
// FIXME  待修復(fù) 
// XXX    實(shí)現(xiàn)方法待確認(rèn) 
// NOTE   代碼功能說明 
// HACK   此處寫法有待優(yōu)化 
// BUG    此處有Bug 
const arr = [] 

Tips：

• 為什么 // 注釋可以在 .less 或 .scss 文件中使用，但是在 .html 和 .css 文件中不生效？
  • 在 MDN 中關(guān)于 CSS 注釋只有 /* */ 一種語法。但是在 LESS 和 SCSS 中支持注釋的語法和 js 中保持一致，有單行注釋 // 和多行注釋 /* */ 兩種。單行注釋編譯之后不會被保留。
• 單行注釋為什么有時(shí)候?qū)懺诖a上方，有時(shí)候?qū)懺诖a后方？
  • 注釋可以書寫在代碼中的任意位置。個人理解，一般寫在代碼上方的時(shí)候意為對后面一段代碼的注釋，而寫在代碼后方的時(shí)候意為對本行代碼的注釋。

注釋寫法規(guī)范

• 文件注釋

  • 位于文件頭部，一般包含概要、作者、版本改動信息以及修改時(shí)間等內(nèi)容

/* 
* 簡述當(dāng)前文件功能 
* @author 作者名稱 
* @version 版本號 最近編輯時(shí)間 
* @description 該版本改動信息 
*/ 

• 單行注釋

  • 總是在 // 后留一個空格

// 這是一行注釋 

• 多行注釋

  • 總是保持星號縱向?qū)R（結(jié)束符前留一個空格）
  • 不要在開始符、結(jié)束符所在行寫注釋
  • 盡量使用單行注釋代替多行注釋
  • 注釋函數(shù)時(shí)，推薦使用多行注釋

/* 
這里有一行注釋 
這里有一行注釋 
這里有一行注釋 
*/ 

• 函數(shù)注釋

  • 其間每一行都以 * 開頭，且與第一行第一個 * 對齊
  • 注釋內(nèi)容與 * 間留一個空格
  • 必須包含標(biāo)簽注釋。例： ```javascript /**

• 方法說明

• @method 方法名

• @for 所屬類名

• @param {參數(shù)類型} 參數(shù)名 參數(shù)說明

• @return {返回值類型} 返回值說明

• /

注釋常用標(biāo)簽用法

• @type {typeName}
  • * 表示任何類型
  • ? 表示可以為 null
  • ! 表示不能為 null
  • [] 表示數(shù)組 ```javascript /**
• @type {number}
• / var foo1;

/**

• @type {*}
• @desc 任何類型
• / var foo2;

/**

• @type {?string}
• @desc string或者null
• / var foo3;

* @param {<type>} name - some description 
    * 非必傳參數(shù)需給參數(shù)名加上'[]' 
    * 參數(shù)如有默認(rèn)值需用'='表示 
    * 如果參數(shù)是object，可繼續(xù)用`@param`對其屬性進(jìn)行詳細(xì)說明 
    * 若干個參數(shù)用`...`表示 
```javascript 
/** 
 * @func 
 * @desc 一個帶參數(shù)的函數(shù) 
 * @param {string} a - 參數(shù)a 
 * @param {number} b=1 - 參數(shù)b默認(rèn)值為1 
 * @param {string} c=1 - 參數(shù)c有兩種支持的取值  1—表示x  2—表示xx 
 * @param {object} d - 參數(shù)d為一個對象 
 * @param {string} d.e - 參數(shù)d的e屬性 
 * @param {object[]} g - 參數(shù)g為一個對象數(shù)組 
 * @param {string} g.h - 參數(shù)g數(shù)組中一項(xiàng)的h屬性 
 * @param {string} [j] - 參數(shù)j是一個可選參數(shù) 
 */ 
 function foo(a, b, c, d, g, j) {} 
 
/** 
 * @func 
 * @desc 一個帶若干參數(shù)的函數(shù) 
 * @param {...string} a - 參數(shù)a 
 */ 
function bar(a) {} 

了解更多可查看 JSDoc

拓展篇

IE 條件注釋（IE5+）

IE 條件注釋分為以下幾種情況：

• 只允許 IE 解釋執(zhí)行 <!--[if IE]><![endif]-->

• 只允許 IE 特定版本解釋執(zhí)行 <!--[if IE 7]><![endif]-->

• 只允許非 IE 特定版本執(zhí)行注釋 <!--[if !IE 7]><![endif]-->

• 只允許高于或低于 IE 特定版本執(zhí)行注釋 <!--[if gt IE 7]><![endif]-->

<head> 
    <title>IE 條件注釋</title> 
 
    <!-- 是 IE 時(shí) --> 
  <!--[if IE]>  
      <link href="style.css" rel="stylesheet" type="text/css" /> 
  <![endif]--> 
 
  <!-- 是 IE 7 時(shí) --> 
        <!--[if IE 7]> 
     <link href="style.css" rel="stylesheet" type="text/css" /> 
  <![endif]--> 
 
  <!-- 不是 IE 7 時(shí) --> 
    <!--[if !IE 7]> 
      <link href="style.css" rel="stylesheet" type="text/css" /> 
  <![endif]--> 
 
    <!-- 大于 IE 7 時(shí) --> 
    <!--[if gt IE 7]> 
     <link href="style.css" rel="stylesheet" type="text/css" /> 
  <![endif]--> 
 
    <!-- 小于 IE 7 時(shí) --> 
     <!--[if lt IE 7]> 
     <link href="style.css" rel="stylesheet" type="text/css" /> 
  <![endif]--> 
</head> 

# （井號）注釋 和 ''' （三引號）注釋

• # 一般出現(xiàn)在各種腳本配置文件中，用法與 JS 單行注釋 // 基本相同。Python 中也常常用到
• ''' 是 Python 中的多行注釋語法，用 ''' ''' 包含被注釋的段落

# python 的單行注釋一 
  print("I could have code like this.") # python 的單行注釋二 

print("This won't run.") # 被注釋的代碼

''' 被三引號包裹的段落 可以隨意折行 也可以注釋代碼 print("This won't run.") '''

#### 注釋“被執(zhí)行”了？ 
 
眾所周知，注釋的代碼是不會被執(zhí)行的。但是小編在查資料時(shí)看到了一段比較有意思的代碼， Java 中的一行注釋“被執(zhí)行”了？ 
 
 
```java 
public class Test { 
    public static void main(String[] args) { 
        String name = "趙大"; 
        // \u000dname="錢二"; 
        System.out.println(name); 
    } 
} 

這段代碼執(zhí)行后的結(jié)果為 錢二 ，也就是說在這段代碼中，“被注釋”的那行代碼生效了！

這段代碼的問題出在 \u000d 這串特殊字符上。 \u000d 是一串 Unicode 字符，代表換行符。Java 編譯器不僅會編譯代碼，還會解析 Unicode 字符。在上面這段代碼把 \u000d 給解析了，后面的代碼就到了下面一行，超出了被注釋的范圍（單行注釋的注釋范圍僅在當(dāng)前行），所以執(zhí)行結(jié)果為 錢二 而非 趙大 。（如下）

public class Test { 
    public static void main(String[] args) { 
        String name = "趙大"; 
        // 
        name="錢二"; 
        System.out.println(name); 
    } 
} 

​ 所以本質(zhì)上在代碼執(zhí)行的時(shí)候 name="錢二" 并沒有被注釋，而是被換了行（奇怪的知識增加了）。 所以切記，注釋確實(shí)是不會被執(zhí)行的哦！

注釋相關(guān)插件

​ 在這里推薦幾個個人認(rèn)為比較好用的注釋相關(guān)的Vscode插件，可在 setting.json 文件下自定義設(shè)置（可通過 '文件—首選項(xiàng)—設(shè)置'，打開 Vscode 文件 settings.json ）

• koroFileHeader 在 vscode 中用于生成文件頭部注釋和函數(shù)注釋的插件
• 文件頭部添加注釋
  • 在文件開頭添加注釋，記錄文件信息/文件的傳參/出參等
  • 支持用戶高度自定義注釋選項(xiàng), 適配各種需求和注釋。
  • 保存文件的時(shí)候，自動更新最后的編輯時(shí)間和編輯人
  • 快捷鍵： window ： ctrl+alt+i ， mac ： ctrl+cmd+i ， linux ： ctrl+meta+i

• 在光標(biāo)處添加函數(shù)注釋
  • 在光標(biāo)處自動生成一個注釋模板
  • 支持用戶高度自定義注釋選項(xiàng)
  • 快捷鍵： window ： ctrl+alt+t , mac ： ctrl+cmd+t , linux : ctrl+meta+t
  • 快捷鍵不可用很可能是被占用了
  • 可自定義默認(rèn)參數(shù)

• Better Comments 通過使用警報(bào)，信息，TODO 等進(jìn)行注釋來改善代碼注釋。使用此擴(kuò)展，您將能夠?qū)⒆⑨尫诸悶椋?
  • 快訊
  • 查詢
  • 待辦事項(xiàng)
  • 強(qiáng)調(diào)
  • 注釋掉的代碼也可以設(shè)置樣式，以使代碼不應(yīng)該存在
  • 可自定義指定其他所需的注釋樣式

• TODO Highlight 突出顯示TODO，F(xiàn)IXME和任何關(guān)鍵字
  • 高亮內(nèi)置關(guān)鍵字，可通過自定義設(shè)置覆蓋外觀
  • 也可自定義關(guān)鍵字

用事實(shí)說話

口說無憑，眼見為實(shí)。下面我們看下實(shí)際開發(fā)中的具體情況：

• 沒有注釋

const noWarehousetemIds = beSelectSkucontainer.reduce((arr, itemId) => { 
  const res = Object.keys(selectRowskey[itemId]).every((skuId) => { 
    const sku = selectRowskey[itemId][skuId]; 
    return !!sku.warehouseCode || lodashGet(warehouses, '[0].code'); 
  }); 
  if (!res) { 
    arr.push(itemId); 
  } 
  return arr; 
}, []); 
if (noWarehousetemIds.length > 0 || noStockItemIds.length > 0) { 
  const itemIds = Array.from(new Set([...noWarehousetemIds, ...noStockItemIds])); 
  const itemNames = itemIds.map(i => this.itemNameMap[i].itemName); 
  return Modal.warning({ 
    title: '錯誤提示', 
    content: `“${itemNames.join(',')}”庫存信息未完善，請完善庫存信息`, 
  }); 
} 

• 一般般的注釋

// 遍歷當(dāng)前所有選中的sku，查找出沒有庫存的itemId 
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => { 
const res = Object.keys(selectRowskey[itemId]).every((skuId) => { 
  const sku = selectRowskey[itemId][skuId]; 
  return !!sku.stockQuantity; 
}); 
if (!res) { 
  arr.push(itemId); 
} 
return arr; 
}, []); 
// 有一條sku的庫存為空時(shí)進(jìn)入校驗(yàn) 
if (noStockItemIds.length > 0) { 
const itemNames = itemIds.map(i => this.itemNameMap[i].itemName); 
return Modal.warning({ 
  title: '錯誤提示', 
  content: `“${itemNames.join(',')}”庫存信息未完善，請完善庫存信息`, 
}); 
} 

• 更好的注釋

// 遍歷當(dāng)前所有選中的sku，查找出沒有庫存的itemId 
const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => { 
  // selectRowskey是一個對象，以itemId為key，sku對象作為value，sku對象以skuId作為key，sku作為value，只有selectRowskey下所有itemId下的sku都有庫存才算校驗(yàn)通過 
  /* 
      數(shù)據(jù)格式: 
      selectRowskey: { 
        12345678: { // itemId 
            123456: { // skuId 
            name: 'sku', 
            } 
        } 
      } 
    */ 
  const res = Object.keys(selectRowskey[itemId]).every((skuId) => { 
      const sku = selectRowskey[itemId][skuId]; 
      return !!sku.stockQuantity; 
  }); 
  // 只要有一條sku沒有庫存時(shí)，就塞到arr中，返回給noStockItemIds數(shù)組 
  if (!res) { 
      arr.push(itemId); 
  } 
  return arr; 
}, []); 
// 有一條sku的庫存為空時(shí)進(jìn)入校驗(yàn) 
if (noStockItemIds.length > 0) { 
  // 根據(jù)id查找商品名稱 
  const itemNames = itemIds.map(i => this.itemNameMap[i].itemName); 
  Modal.warning({ 
      title: '錯誤提示', 
      content: `“${itemNames.join(',')}”庫存信息未完善，請完善庫存信息`, 
  }); 
} 

看到上面這段代碼可以很明顯的體會到有沒有注釋以及注釋寫的清不清楚的重要性。若是寫了注釋但仍然看不懂，那還不如不寫。

所以注釋也不是隨便寫一寫就可以的，要描述某段代碼的功能，注明邏輯，讓開發(fā)者可以”無腦“瀏覽。

之前在工作群中看到有人發(fā)過這樣一張圖（如下圖），個人認(rèn)為是一個很好的代碼注釋的范例：

結(jié)語

看到這里，對于注釋的重要性各位已經(jīng)有自己的認(rèn)知。還有幾點(diǎn)是我們寫注釋時(shí)需要注意的：

• 注釋內(nèi)容要簡潔、清楚明了。注釋簡述功能或?qū)崿F(xiàn)邏輯即可，無需每行代碼都添加注釋

• 代碼若有修改，切記同步修改對應(yīng)的注釋。不要出現(xiàn)過期的注釋，否則會起到反作用