優雅的使用注釋

前言

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

一、語法

1. CSS 注釋

/* css 注釋 */

2. JavaScript 注釋

// 單行注釋 /** * 多行注釋，注意第一行最好用兩個 * * ... */ /* 當然，除了兩端的 * 必須加以外，其他的 * 不加也行 ... */

二、基本使用

1. 單行注釋

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

/* 用注釋備注 CSS 類名的功能 */ /* 頂部組件 */ .hd { position: fixed; width: 100vw; } /* 版心 */ .container { margin: 16px auto; width: 1200px; }

// 用單行注釋備注簡單的信息 const userName = ""; // 用戶名 const userAvatar = ""; // 用戶頭像 // xxx函數 const myFunction = () => {};

2. 多行注釋

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

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

小伙伴們可能看到了，一個傳入五個參數，內部數行代碼的函數竟然只有短短的一行注釋，也許你開發的時候能記住這個函數的用途以及參數的類型以及是否必傳等，但是如果你隔了一段時間再回頭看之前的代碼，那么簡短的注釋就可能變成你的困擾。

更不用說沒有注釋，不寫注釋一時爽，回看代碼火葬場。

寫注釋的目的在于提高代碼的可讀性。相比之下，下面的注釋就清晰的多：

/** * 調整滾動距離 * 用于顯示給定 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); }; };

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

/** * 函數名稱 * 函數簡介 * @param 參數1 參數1數據類型 是否必傳 參數1描述 * @param 參數2 參數2數據類型 是否必傳 參數2描述 * @param ... * @returns 返回值 */

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

當然，一個好的變量/函數名也能降低閱讀者的思考成本，可以移步到我的文章：《優雅的命名》。

三、進階使用

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

/* 以下代碼僅為示例 */ /* 模塊1 */ /* 類名1 */ .class-a {} /* 類名2 */ .class-b {} /* 類名3 */ .class-c {} /* 模塊2 */ /* 類名4 */ .class-d {} /* 類名5 */ .class-e {} /* ... */

// 以下代碼僅為示例 // 模塊1 // 變量1 const value1 = ""; // 變量2 const value2 = ""; // 變量3 const value3 = ""; // 函數1 const myFunction1 = () => {}; // 模塊2 // 變量4 const value4 = ""; // 變量5 const value5 = ""; // 變量6 const value6 = ""; // 函數2 const myFunction2 = () => {}; // ...

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

/* ------------------------ 模塊1 ------------------------ */ /* 類名1 */ .class-a {} /* 類名2 */ .class-b {} /* 類名3 */ .class-c {} /* ------------------------ 模塊2 ------------------------ */ /* 類名4 */ .class-d {} /* 類名5 */ .class-e {} /* ... */

// 以下代碼僅為示例 /* ======================== 模塊1 ======================== */ // 變量1 const value1 = ""; // 變量2 const value2 = ""; // 變量3 const value3 = ""; // 函數1 const myFunction1 = () => {}; /* ======================== 模塊2 ======================== */ // 變量4 const value4 = ""; // 變量5 const value5 = ""; // 變量6 const value6 = ""; // 函數2 const myFunction2 = () => {}; // ...

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

“華麗的”分割線：

/* ------------------------ 華麗的分割線 ------------------------ */ /* ======================== 華麗的分割線 ======================== */

四、擴展

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

1. Better Comments

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

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

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

2. koroFileHeader

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

3. JavaScript Comment Snippet

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

小結

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

CSS JavaScript web前端

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。