編寫相親交友原始碼，註釋方面應該重視哪些問題？

雲豹科技程式設計師發表於2021-10-18
原始碼

前言

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

一、語法

1.1 CSS 註釋

/* css 註釋 */

1.2 JavaScript 註釋

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

二、基本使用

2.1 單行註釋

一般情況下，單行註釋會出現在相親交友原始碼的正上方，起到提示的作用：
/* 用註釋備註 CSS 類名的功能 */
/* 頂部元件 */
.hd {
  position: fixed;
  width: 100vw;
}
/* 版心 */
.container {
  margin: 16px auto;
  width: 1200px;
}
// 用單行註釋備註簡單的資訊
const userName = ""; // 使用者名稱
const userAvatar = ""; // 使用者頭像
// xxx函式
const myFunction = () => {};

2.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 的註釋“分割線”建議使用多行註釋。
 /* ------------------------ 華麗的分割線 ------------------------ */
 
/* ======================== 華麗的分割線 ======================== */

結語

不得不說註釋在相親交友原始碼編寫過程中真的相當重要，為了寫出更優雅，更易於維護的程式碼，我們也應當把最重要的資訊寫到註釋裡。相親交友原始碼的 README.markdown 和相親交友原始碼中的註釋就喜像是專案的 說明書 一樣，能讓非專案開發者更快的讀懂程式碼的含義以及編碼的思想。讓程式碼成就我們，讓程式碼改變世界，讓註釋，伴我同行！

本文轉載自網路，轉載僅為分享乾貨知識，如有侵權歡迎聯絡雲豹科技進行刪除處理

原文連結：

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/69996194/viewspace-2837947/，如需轉載，請註明出處，否則將追究法律責任。

相關文章