一個巧合，我把文件寫進了程式碼裡
阿新 • • 發佈：2021-02-22
最近因為公司業務的調整，專案需要開發大量的業務元件、高複用邏輯提供給客戶使用。當各類元件、程式碼多了以後，加上團隊內幾個成員書寫習慣、開發思想的不同，出現了好多問題。尤其兩個問題最嚴重：
1. 大量的業務元件/業務邏輯需要通過查原始碼的方式，或者問寫元件的人，才能知道元件是否有自己需要的屬性/鉤子方法
2. 有些元件因為產品需求 + 口頭溝通 + 需求妥協，只能應用於某一個特定的情況下，其他人看設計圖或者邏輯差不多相似就直接拿過來用，結果發現用不了/各種問題
為了解決這兩個問題，就開始要求組員在開發業務元件的同時，必須寫對應的開發文件/程式碼註釋。一開始還好，中後期開發文件的更新明顯跟不上元件的迭代，逐漸地又回到了靠嘴問的情況，第2個問題也是隨著時間推移又回到了起點。
某天通過`VS Code`除錯程式碼的時候忽然發現，用滑鼠在原生語法和`react`的方法上懸浮幾秒鐘，就會出現一個提示框，裡面有一些節點/元件/方法的簡單介紹，引數等。
對，這就是我想要的效果！
原生語法 （如`document.getElementById`）：
`react`的方法（如`useState`）：
通過`ctrl + 滑鼠左鍵`點開型別定義，發現提示框裡的內容其實是相關程式碼上方的註釋。
按照型別定義裡面的註釋，我在程式碼裡輸入`/**`的時候出現瞭如下圖的提示。
拿著關鍵詞我去`VS Code`的官網搜尋了一番，在官網搜到了答案（[點選此處](https://code.visualstudio.com/Docs/languages/javascript#_jsdoc-support)）。
> VS Code understands many standard [JSDoc](https://jsdoc.app/) annotations, and uses these annotations to provide rich [IntelliSense](https://code.visualstudio.com/Docs/languages/javascript#_intellisense).
>
> VS Code 可以理解標準的JSDoc程式碼註釋，並使用這些註釋提供豐富的智慧感知（如智慧程式碼完成，懸停資訊和簽名信息）
而`JSDoc`的語法也非常簡單，只需要保證註釋的開頭是`/**`即可，其他與多行註釋沒有什麼差別。（更多語法：[點選此處](https://jsdoc.app/)）
```javascript
/** 這樣便建立了一個程式碼提醒 */
function remind() {}
```
上手寫個元件試試效果！
```javascript
import React, { useEffect, useState } from 'react'
interface KeywordInterface {
/**
* 關鍵詞
*/
keyword?: string;
/**
* 高亮顯示的顏色，支援hex、hsl、rgba、keywords
*/
color?: string;
children?: string;
}
/**
* 關鍵詞高亮元件
*
* @example
*
* @param { string } keyword - 關鍵詞
* @param { string } color - 高亮顯示的顏色
*/
const LightKeyword: