前言

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

一、語法

1.1 CSS 注釋

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

1.2 JavaScript 注釋

// 單行注釋

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

二、基本使用

2.1 單行注釋

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

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

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

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

// 用單行注釋備注簡單的信息

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

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

2.2 多行注釋

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

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

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

/**
 * 調(diào)整滾動距離
 * 用于顯示給定 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ù)制代碼

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

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

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

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

三、進階使用

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

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

 /* 模塊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ù)制代碼

效果有了，但是似乎不太明顯，因此我們在注釋中增加 - 或者 = 來進行分割試試：

 /* ------------------------ 模塊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ù)制代碼

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

“華麗的”分割線：

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

四、擴展

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

4.1 Better Comments

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

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

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

4.2 koroFileHeader

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

4.3 JavaScript Comment Snippet

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

結(jié)語

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