自拍偷在线精品自拍偷,亚洲欧美中文日韩v在线观看不卡

編寫(xiě)高質(zhì)量可維護(hù)的代碼：一目了然的注釋

作者：佚名
新聞 前端
有一些人認(rèn)為，好的代碼是自我解釋的。合適的命名和優(yōu)秀的代碼的確可以減輕開(kāi)發(fā)人員閱讀代碼的工作量，對(duì)于不是特別復(fù)雜的代碼可能確實(shí)可以做到自我解釋。

 前言

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

編程語(yǔ)言中對(duì)“注釋”的解釋

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

[[344072]]

要不要加注釋?zhuān)繛槭裁匆幼⑨專(zhuān)?/h3>

注釋的存在就是為了方便自己的二次閱讀和代碼維護(hù)以及項(xiàng)目交接?？梢愿玫睦斫獯a，有助于提高協(xié)作效率，加快開(kāi)發(fā)進(jìn)程。

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

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

基礎(chǔ)篇

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

注釋的分類(lèi)

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

  • CSS 中的注釋

  1. <style> 
  2.   div { 
  3.       /* color: #fff;  */ 
  4.    } 
  5. </style> 
  1. div { 
  2.     /* color: #fff;  */ 
  3. } 
  1. div { 
  2.     /* color: #fff;*/  /* 多行注釋*/ 
  3.     // font-size: 14px; // 單行注釋 
  4.     background: #000; 
  5. } 
  • 在 HTML 中
  • 在 .css文件中
  • 在 .less 或 .scss 文件中

  • JS 中的注釋

    • 用法

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

    • 單行注釋?zhuān)ㄐ凶⑨專(zhuān)?mdash;— 以 // 開(kāi)頭。任何位于 // 之后的文本都會(huì)被注釋

  • 多行注釋?zhuān)▔K注釋?zhuān)?mdash;—以 /* 開(kāi)頭，以 */ 結(jié)尾。任何位于 /* 和 */ 之間的文本都會(huì)被注釋

    1. /* 
    2.   這是多行注釋 
    3.   定義一個(gè)數(shù)組 
    4. */ 
    5. var ary = []; 

  1. * 用注釋來(lái)阻止代碼執(zhí)行  —— 被注釋的 JS 代碼將不被執(zhí)行 
  2.  
  3. ```js 
  4. //alert("123")  // 執(zhí)行時(shí)未彈出該信息 
  5. alert("456")  // 執(zhí)行時(shí)彈出該信息 
  6. ``` 

  • 函數(shù)注釋

    • 一般以 /** 開(kāi)頭，以 */ 結(jié)尾。任何位于 /** 和 */ 之間的文本都會(huì)被注釋
  1. /** 
  2.  * 提交 
  3.  * 
  4.  * @method onSubmit 
  5.  * @param {[Object]} 提交數(shù)據(jù) 
  6.  * @return  {[Bollean]}  [返回是否提交成功 ] 
  7.  */ 
  8. const onSubmit = (params = {}) => { 
  9.   const result = false; 
  10.     if (params) { 
  11.             result = true; 
  12.         } 
  13.     return result; 
  14. }; 
  • 特殊標(biāo)記注釋
    • TODO 在該注釋處有功能代碼待編寫(xiě)，待實(shí)現(xiàn)的功能在說(shuō)明中會(huì)簡(jiǎn)略說(shuō)明
    • FIXME 在該注釋處代碼需要修正，甚至代碼是錯(cuò)誤的，不能工作，需要修復(fù)，如何修正會(huì)在說(shuō)明中簡(jiǎn)略說(shuō)明
    • XXX 在該注釋處代碼雖然實(shí)現(xiàn)了功能，但是實(shí)現(xiàn)的方法有待商榷，希望將來(lái)能改進(jìn)，要改進(jìn)的地方會(huì)在說(shuō)明中簡(jiǎn)略說(shuō)明
    • NOTE 在該注釋處說(shuō)明代碼如何工作
    • HACK 在該注釋處編寫(xiě)得不好或格式錯(cuò)誤，需要根據(jù)自己的需求去調(diào)整程序代碼
    • BUG 在該注釋處有 Bug
  1. // TODO功能未完成，待完善 
  2. // FIXME  待修復(fù) 
  3. // XXX    實(shí)現(xiàn)方法待確認(rèn) 
  4. // NOTE   代碼功能說(shuō)明 
  5. // HACK   此處寫(xiě)法有待優(yōu)化 
  6. // BUG    此處有Bug 
  7. const arr = [] 

Tips：

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

注釋寫(xiě)法規(guī)范

  • 文件注釋

    • 位于文件頭部，一般包含概要、作者、版本改動(dòng)信息以及修改時(shí)間等內(nèi)容
  1. /* 
  2. * 簡(jiǎn)述當(dāng)前文件功能 
  3. * @author 作者名稱 
  4. * @version 版本號(hào) 最近編輯時(shí)間 
  5. * @description 該版本改動(dòng)信息 
  6. */ 

  • 單行注釋

    • 總是在 // 后留一個(gè)空格
  1. // 這是一行注釋 

  • 多行注釋

    • 總是保持星號(hào)縱向?qū)R（結(jié)束符前留一個(gè)空格）
    • 不要在開(kāi)始符、結(jié)束符所在行寫(xiě)注釋
    • 盡量使用單行注釋代替多行注釋
    • 注釋函數(shù)時(shí)，推薦使用多行注釋
  1. /* 
  2. 這里有一行注釋 
  3. 這里有一行注釋 
  4. 這里有一行注釋 
  5. */ 

  • 函數(shù)注釋

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

  • 方法說(shuō)明

  • @method 方法名

  • @for 所屬類(lèi)名

  • @param {參數(shù)類(lèi)型} 參數(shù)名 參數(shù)說(shuō)明

  • @return {返回值類(lèi)型} 返回值說(shuō)明

  • /

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

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

/**

  • @type {*}
  • @desc 任何類(lèi)型
  • / var foo2;

/**

  • @type {?string}
  • @desc string或者null
  • / var foo3;
  1. * @param {<type>} name - some description 
  2.     * 非必傳參數(shù)需給參數(shù)名加上'[]' 
  3.     * 參數(shù)如有默認(rèn)值需用'='表示 
  4.     * 如果參數(shù)是object，可繼續(xù)用`@param`對(duì)其屬性進(jìn)行詳細(xì)說(shuō)明 
  5.     * 若干個(gè)參數(shù)用`...`表示 
  6. ```javascript 
  7. /** 
  8.  * @func 
  9.  * @desc 一個(gè)帶參數(shù)的函數(shù) 
  10.  * @param {string} a - 參數(shù)a 
  11.  * @param {number} b=1 - 參數(shù)b默認(rèn)值為1 
  12.  * @param {string} c=1 - 參數(shù)c有兩種支持的取值  1—表示x  2—表示xx 
  13.  * @param {object} d - 參數(shù)d為一個(gè)對(duì)象 
  14.  * @param {string} d.e - 參數(shù)d的e屬性 
  15.  * @param {object[]} g - 參數(shù)g為一個(gè)對(duì)象數(shù)組 
  16.  * @param {string} g.h - 參數(shù)g數(shù)組中一項(xiàng)的h屬性 
  17.  * @param {string} [j] - 參數(shù)j是一個(gè)可選參數(shù) 
  18.  */ 
  19.  function foo(a, b, c, d, g, j) {} 
  20.  
  21. /** 
  22.  * @func 
  23.  * @desc 一個(gè)帶若干參數(shù)的函數(shù) 
  24.  * @param {...string} a - 參數(shù)a 
  25.  */ 
  26. function bar(a) {} 

了解更多可查看 JSDoc

拓展篇

IE 條件注釋?zhuān)↖E5+）

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]-->

  1. <head> 
  2.     <title>IE 條件注釋</title> 
  3.  
  4.     <!-- 是 IE 時(shí) --> 
  5.   <!--[if IE]>  
  6.       <link href="style.css" rel="stylesheet" type="text/css" /> 
  7.   <![endif]--> 
  8.  
  9.   <!-- 是 IE 7 時(shí) --> 
  10.         <!--[if IE 7]> 
  11.      <link href="style.css" rel="stylesheet" type="text/css" /> 
  12.   <![endif]--> 
  13.  
  14.   <!-- 不是 IE 7 時(shí) --> 
  15.     <!--[if !IE 7]> 
  16.       <link href="style.css" rel="stylesheet" type="text/css" /> 
  17.   <![endif]--> 
  18.  
  19.     <!-- 大于 IE 7 時(shí) --> 
  20.     <!--[if gt IE 7]> 
  21.      <link href="style.css" rel="stylesheet" type="text/css" /> 
  22.   <![endif]--> 
  23.  
  24.     <!-- 小于 IE 7 時(shí) --> 
  25.      <!--[if lt IE 7]> 
  26.      <link href="style.css" rel="stylesheet" type="text/css" /> 
  27.   <![endif]--> 
  28. </head> 

# （井號(hào)）注釋 和 ''' （三引號(hào)）注釋

  • # 一般出現(xiàn)在各種腳本配置文件中，用法與 JS 單行注釋 // 基本相同。Python 中也常常用到
  • ''' 是 Python 中的多行注釋語(yǔ)法，用 ''' ''' 包含被注釋的段落
  1. # python 的單行注釋一 
  2.   print("I could have code like this.") # python 的單行注釋二 

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

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

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

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

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

  1. public class Test { 
  2.     public static void main(String[] args) { 
  3.         String name = "趙大"; 
  4.         // 
  5.         name="錢(qián)二"; 
  6.         System.out.println(name); 
  7.     } 
  8. } 

​ 所以本質(zhì)上在代碼執(zhí)行的時(shí)候 name="錢(qián)二" 并沒(méi)有被注釋?zhuān)潜粨Q了行（奇怪的知識(shí)增加了）。 所以切記，注釋確實(shí)是不會(huì)被執(zhí)行的哦！

注釋相關(guān)插件

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

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

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

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

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

用事實(shí)說(shuō)話

口說(shuō)無(wú)憑，眼見(jiàn)為實(shí)。下面我們看下實(shí)際開(kāi)發(fā)中的具體情況：

  • 沒(méi)有注釋
  1. const noWarehousetemIds = beSelectSkucontainer.reduce((arr, itemId) => { 
  2.   const res = Object.keys(selectRowskey[itemId]).every((skuId) => { 
  3.     const sku = selectRowskey[itemId][skuId]; 
  4.     return !!sku.warehouseCode || lodashGet(warehouses, '[0].code'); 
  5.   }); 
  6.   if (!res) { 
  7.     arr.push(itemId); 
  8.   } 
  9.   return arr; 
  10. }, []); 
  11. if (noWarehousetemIds.length > 0 || noStockItemIds.length > 0) { 
  12.   const itemIds = Array.from(new Set([...noWarehousetemIds, ...noStockItemIds])); 
  13.   const itemNames = itemIds.map(i => this.itemNameMap[i].itemName); 
  14.   return Modal.warning({ 
  15.     title: '錯(cuò)誤提示', 
  16.     content: `“${itemNames.join(',')}”庫(kù)存信息未完善，請(qǐng)完善庫(kù)存信息`, 
  17.   }); 
  18. } 
  • 一般般的注釋
  1. // 遍歷當(dāng)前所有選中的sku，查找出沒(méi)有庫(kù)存的itemId 
  2. const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => { 
  3. const res = Object.keys(selectRowskey[itemId]).every((skuId) => { 
  4.   const sku = selectRowskey[itemId][skuId]; 
  5.   return !!sku.stockQuantity; 
  6. }); 
  7. if (!res) { 
  8.   arr.push(itemId); 
  9. } 
  10. return arr; 
  11. }, []); 
  12. // 有一條sku的庫(kù)存為空時(shí)進(jìn)入校驗(yàn) 
  13. if (noStockItemIds.length > 0) { 
  14. const itemNames = itemIds.map(i => this.itemNameMap[i].itemName); 
  15. return Modal.warning({ 
  16.   title: '錯(cuò)誤提示', 
  17.   content: `“${itemNames.join(',')}”庫(kù)存信息未完善，請(qǐng)完善庫(kù)存信息`, 
  18. }); 
  19. } 
  • 更好的注釋
  1. // 遍歷當(dāng)前所有選中的sku，查找出沒(méi)有庫(kù)存的itemId 
  2. const noStockItemIds = beSelectSkucontainer.reduce((arr, itemId) => { 
  3.   // selectRowskey是一個(gè)對(duì)象，以itemId為key，sku對(duì)象作為value，sku對(duì)象以skuId作為key，sku作為value，只有selectRowskey下所有itemId下的sku都有庫(kù)存才算校驗(yàn)通過(guò) 
  4.   /* 
  5.       數(shù)據(jù)格式: 
  6.       selectRowskey: { 
  7.         12345678: { // itemId 
  8.             123456: { // skuId 
  9.             name: 'sku', 
  10.             } 
  11.         } 
  12.       } 
  13.     */ 
  14.   const res = Object.keys(selectRowskey[itemId]).every((skuId) => { 
  15.       const sku = selectRowskey[itemId][skuId]; 
  16.       return !!sku.stockQuantity; 
  17.   }); 
  18.   // 只要有一條sku沒(méi)有庫(kù)存時(shí)，就塞到arr中，返回給noStockItemIds數(shù)組 
  19.   if (!res) { 
  20.       arr.push(itemId); 
  21.   } 
  22.   return arr; 
  23. }, []); 
  24. // 有一條sku的庫(kù)存為空時(shí)進(jìn)入校驗(yàn) 
  25. if (noStockItemIds.length > 0) { 
  26.   // 根據(jù)id查找商品名稱 
  27.   const itemNames = itemIds.map(i => this.itemNameMap[i].itemName); 
  28.   Modal.warning({ 
  29.       title: '錯(cuò)誤提示', 
  30.       content: `“${itemNames.join(',')}”庫(kù)存信息未完善，請(qǐng)完善庫(kù)存信息`, 
  31.   }); 
  32. } 

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

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

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

結(jié)語(yǔ)

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

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

  • 代碼若有修改，切記同步修改對(duì)應(yīng)的注釋。不要出現(xiàn)過(guò)期的注釋?zhuān)駝t會(huì)起到反作用

 

責(zé)任編輯：張燕妮 來(lái)源： ZooTeam Blog
代碼開(kāi)發(fā)注釋
相關(guān)推薦

2023-11-10 08:56:49

Springboot常用的注解

2023-09-14 10:42:46

SQL數(shù)據(jù)庫(kù)

2011-03-04 10:11:09

JavascriptAPI

2010-03-10 09:06:58

Windows 7啟動(dòng)時(shí)間

2010-01-26 08:58:17

Windows 7啟動(dòng)時(shí)間

2009-11-24 18:20:16

曙光Gridview管理

2015-08-25 08:29:11

編寫(xiě)高質(zhì)量命名

2011-12-29 15:02:27

JavaScript

2015-08-25 08:42:36

高質(zhì)量代碼命名

2015-03-22 06:25:23

監(jiān)控寶云智慧

2017-07-14 09:54:47

代碼函數(shù)程序

2015-07-03 09:41:05

腳本編程編程語(yǔ)言比較

2021-03-12 14:06:03

谷歌代碼開(kāi)發(fā)

2012-09-13 10:44:18

Python代碼

2021-01-12 16:28:41

5G運(yùn)營(yíng)商韓國(guó)

2015-07-13 10:48:44

OC代碼程序員

2023-10-31 16:22:31

代碼質(zhì)量軟件開(kāi)發(fā)Java

2023-09-27 23:32:46

Python監(jiān)控進(jìn)程

2024-03-07 11:39:24

HadolintDockerfile工具

2023-10-07 09:34:03

數(shù)據(jù)可視化
點(diǎn)贊
收藏

51CTO技術(shù)棧公眾號(hào)