前言

注釋相信小伙伴們都不陌生，但是就是這個(gè)小小的注釋就像項(xiàng)目文檔一樣讓許多小伙伴又愛(ài)又恨。不喜歡寫注釋，又討厭別人不寫注釋。在此我們將討論 JavaScript 和 CSS 的注釋，希望通過(guò)這篇文章，讓你重拾對(duì)注釋的喜愛(ài)，讓編碼的樂(lè)趣如星辰大海。

一、語(yǔ)法

1.1 CSS 注釋

/* css 注釋 */
復(fù)制代碼

1.2 JavaScript 注釋

// 單行注釋

/**
 * 多行注釋，注意第一行最好用兩個(gè) *
 * ...
 */
 
/*
 當(dāng)然，除了兩端的 * 必須加以外，其他的 * 不加也行
 ...
*/
復(fù)制代碼

二、基本使用

2.1 單行注釋

一般情況下，單行注釋會(huì)出現(xiàn)在代碼的正上方，起到提示的作用：

/* 用注釋備注 CSS 類名的功能 */

/* 頂部組件 */
.hd {
  position: fixed;
  width: 100vw;
}

/* 版心 */
.container {
  margin: 16px auto;
  width: 1200px;
}
復(fù)制代碼

// 用單行注釋備注簡(jiǎn)單的信息

const userName = ""; // 用戶名
const userAvatar = ""; // 用戶頭像

// xxx函數(shù)
const myFunction = () => {};
復(fù)制代碼

2.2 多行注釋

多行注釋一般用于需要備注的信息過(guò)多的情況，常常出沒(méi)于 JavaScript 函數(shù)的附近。首先提出一個(gè)問(wèn)題：為什么要用到多行注釋，用單行注釋不香嗎？下面就來(lái)看看下面的代碼：

// xxx函數(shù)
const myFunction = ({ id, name, avatar, list, type }) => {
  // 此處省略 30 行代碼
};
復(fù)制代碼

小伙伴們可能看到了，一個(gè)傳入五個(gè)參數(shù)，內(nèi)部數(shù)行代碼的函數(shù)竟然只有短短的一行注釋，也許你開(kāi)發(fā)的時(shí)候能記住這個(gè)函數(shù)的用途以及參數(shù)的類型以及是否必傳等，但是如果你隔了一段時(shí)間再回頭看之前的代碼，那么簡(jiǎn)短的注釋就可能變成你的困擾。更不用說(shuō)沒(méi)有注釋，不寫注釋一時(shí)爽，回看代碼火葬場(chǎng)。 寫注釋的目的在于提高代碼的可讀性。相比之下，下面的注釋就清晰的多：

/**
 * 調(diào)整滾動(dòng)距離
 * 用于顯示給定 id 元素
 * @param    id        string  必傳    元素 id
 * @param    distance  number  非必傳  距離視口最頂部距離(避免被頂部固定定位元素遮擋)
 * @returns  null
 */
export const scrollToShowElement = (id = "", distance = 0) => {
  return () => {
    if (!id) {
      return;
    };

    const element = document.getElementById(id);
    if (!element) {
      return;
    };

    const top = element?.offsetTop || 0;
    window.scroll(0, top - distance);
  };
};
復(fù)制代碼

對(duì)于復(fù)雜的函數(shù)，函數(shù)聲明上面要加上統(tǒng)一格式的多行注釋，同時(shí)內(nèi)部的復(fù)雜邏輯和重要變量也需要加上單行注釋，兩者相互配合，相輔相成。函數(shù)聲明的多行注釋格式一般為：

/**
 * 函數(shù)名稱
 * 函數(shù)簡(jiǎn)介
 * @param    參數(shù)1    參數(shù)1數(shù)據(jù)類型  是否必傳  參數(shù)1描述
 * @param    參數(shù)2    參數(shù)2數(shù)據(jù)類型  是否必傳  參數(shù)2描述
 * @param    ...
 * @returns  返回值
 */
復(fù)制代碼

多行注釋的優(yōu)點(diǎn)是清晰明了，缺點(diǎn)是較為繁瑣(可以借助編輯器生成 JavaScript 函數(shù)注釋模板)。建議邏輯簡(jiǎn)單的函數(shù)使用單行注釋，邏輯復(fù)雜的函數(shù)和公共/工具函數(shù)使用多行注釋。

當(dāng)然，一個(gè)好的變量/函數(shù)名也能降低閱讀者的思考成本，可以移步到我的文章：《優(yōu)雅的命名 ????》^[2]。

三、進(jìn)階使用

無(wú)論是 css 還是 JavaScript 中，當(dāng)代碼越來(lái)越多的時(shí)候，也使得尋找要改動(dòng)的代碼時(shí)變得越來(lái)越麻煩。所以我們有必要對(duì)代碼按模塊進(jìn)行整理，并在每個(gè)模塊的頂部用注釋，結(jié)束時(shí)使用空行進(jìn)行分割。

 /* 以下代碼僅為示例 */

 /* 模塊1 */
 /* 類名1 */
 .class-a {}

 /* 類名2 */
 .class-b {}

 /* 類名3 */
 .class-c {}

 /* 模塊2 */
 /* 類名4 */
 .class-d {}

 /* 類名5 */
 .class-e {}

 /* ... */
復(fù)制代碼

// 以下代碼僅為示例

// 模塊1
// 變量1
const value1 = "";
// 變量2
const value2 = "";
// 變量3
const value3 = "";
// 函數(shù)1
const myFunction1 = () => {};

// 模塊2
// 變量4
const value4 = "";
// 變量5
const value5 = "";
// 變量6
const value6 = "";
// 函數(shù)2
const myFunction2 = () => {};

// ...
復(fù)制代碼

效果有了，但是似乎不太明顯，因此我們?cè)谧⑨屩性黾?- 或者 = 來(lái)進(jìn)行分割試試：

 /* ------------------------ 模塊1 ------------------------ */
 /* 類名1 */
 .class-a {}

 /* 類名2 */
 .class-b {}

 /* 類名3 */
 .class-c {}

 /* ------------------------ 模塊2 ------------------------ */
 /* 類名4 */
 .class-d {}

 /* 類名5 */
 .class-e {}

 /* ... */
復(fù)制代碼

// 以下代碼僅為示例

/* ======================== 模塊1 ======================== */
// 變量1
const value1 = "";
// 變量2
const value2 = "";
// 變量3
const value3 = "";
// 函數(shù)1
const myFunction1 = () => {};

/* ======================== 模塊2 ======================== */
// 變量4
const value4 = "";
// 變量5
const value5 = "";
// 變量6
const value6 = "";
// 函數(shù)2
const myFunction2 = () => {};

// ...
復(fù)制代碼

能直觀的看出，加長(zhǎng)版的注釋分割效果更好，區(qū)分度更高。高質(zhì)量的代碼往往需要最樸實(shí)無(wú)華的注釋進(jìn)行分割。其中 JavaScript 的注釋“分割線”建議使用多行注釋。

“華麗的”分割線：

 /* ------------------------ 華麗的分割線 ------------------------ */
 
/* ======================== 華麗的分割線 ======================== */
復(fù)制代碼

四、擴(kuò)展

工欲善其事，必先利其器。下面我要推薦幾款 VSCode 編輯器關(guān)于注釋的插件。

4.1 Better Comments

插件介紹：可以改變注釋的顏色，有四種高亮的顏色（默認(rèn)為紅色、橙色、綠色、藍(lán)色）和一種帶刪除線的黑色。顏色可以在插件配置里面修改。下圖為實(shí)例顏色和本人在項(xiàng)目中的用法，一個(gè)注釋對(duì)應(yīng)一種情況。

喜歡花里胡哨的coder們必備插件，有效提高注釋的辨析度和美感，從此愛(ài)上注釋。其改變注釋顏色只需要加上一個(gè)或多個(gè)字符即可，開(kāi)箱即用。

// ! 紅色的高亮注釋,雙斜線后加英文嘆號(hào)     !     配置
// todo 橙色的高亮注釋,雙斜線后加         todo   函數(shù)
// * 綠色的高亮注釋,雙斜線后加            *      變量
// ? 藍(lán)色的高亮注釋,雙斜線后加英文問(wèn)號(hào)     ?     組件
// // 黑色帶刪除線的注釋,雙斜線后加雙斜線  //    說(shuō)明
復(fù)制代碼

4.2 koroFileHeader

插件介紹：文件頭部添加注釋，在光標(biāo)處添加函數(shù)注釋，一鍵添加佛祖保佑永無(wú)BUG、神獸護(hù)體等注釋圖案。

4.3 JavaScript Comment Snippet

插件介紹：可以快速生成 JavaScript 注釋，冷門但是好用。

結(jié)語(yǔ)

不得不說(shuō)注釋在編碼過(guò)程中真的相當(dāng)重要，為了寫出更優(yōu)雅，更易于維護(hù)的代碼，我們也應(yīng)當(dāng)把最重要的信息寫到注釋里。一個(gè)項(xiàng)目的 README.markdown 和項(xiàng)目中的注釋就喜像是項(xiàng)目的 說(shuō)明書 一樣，能讓非項(xiàng)目開(kāi)發(fā)者更快的讀懂代碼的含義以及編碼的思想。讓代碼成就我們，讓代碼改變世界，讓注釋，伴我同行！