在大(dà)多數情況下(xià)，您并不是唯一(yī)在同一(yī)項目或代碼庫上工(gōng)作的人。這意味着其他人可能也會閱讀您的代碼并且必須理解它。

所以，您應該編寫代碼注釋來幫助其他開(kāi)發人員(yuán)去(qù)理解你所寫的代碼。描述函數、函數背後的推理及其輸入和輸出的代碼注釋将加快其他開(kāi)發人員(yuán)的學習過程。特别是對于初級開(kāi)發人員(yuán)，這些信息在學習代碼時會派上用場。

讓我(wǒ)(wǒ)們來看看不同類型的代碼注釋。

1. 文檔注釋——這些注釋的主要目的是快速闡明文件或組件的用途。您可以在 `index` 文件的頂部寫一(yī)個代碼注釋來解釋組件的作用，而不是閱讀組件的整個代碼來了解它的作用。

2. 函數注釋——函數注釋是最有用的注釋類型，可以自動生(shēng)成多種語言。它們描述了函數的用途、它接受的參數以及它生(shēng)成的輸出。通常隻描述公共函數就足夠了，因爲使用您的代碼的開(kāi)發人員(yuán)不會與私有函數交互。

‍3.邏輯注釋 - 邏輯注釋是函數内的注釋，用于闡明複雜(zá)的代碼路徑。

最重要的是，邏輯注釋通常會提供很多詳細的信息。詳細程度會造成更多混亂并降低代碼的可讀性。

代碼注釋：4 個最佳實踐

這是代碼注釋的四個最佳實踐的列表。

1.利用代碼注釋或标簽

許多編程語言定義了代碼注釋标準。 Java 使用 Javadoc，而 JavaScript 使用許多文檔生(shēng)成工(gōng)具支持的 JSDoc 代碼注釋系統。

您應該做好以下(xià)代碼标記：

@desc - 爲您的函數寫下(xià)描述

@param - 描述函數接受的所有輸入參數。确保定義輸入類型。

@returns - 描述返回的輸出。确保定義輸出類型。

@throws - 描述函數可以抛出的錯誤類型

@example - 包含一(yī)個或多個顯示輸入和預期輸出的示例。

2. 寫下(xià)你爲什麽要做某事

許多開(kāi)發人員(yuán)使用注釋來描述他們的代碼正在做什麽。這不一(yī)定是錯誤的。但是，不要忘記包括創建特定功能或組件的原因。此信息稱爲上下(xià)文。上下(xià)文對于讓開(kāi)發人員(yuán)更深入地了解功能或組件背後的設計決策至關重要。當其他開(kāi)發人員(yuán)想要對您的功能或組件進行更改時，此上下(xià)文至關重要。

您經常會看到在函數描述中(zhōng)使用函數名稱的代碼注釋。

3. 不要參考其他文件或評論

參考闡明功能或組件的其他代碼注釋或内部文檔并不是一(yī)個好主意。如果開(kāi)發者想快速掃描代碼以獲得更好的理解，代碼注釋應該清晰。

如果你認爲你需要添加一(yī)個文檔來闡明代碼的目的，這是錯誤代碼的危險信号。

4. 在寫代碼的同時寫注釋

在編寫代碼的同時編寫注釋聽(tīng)起來是很理所應當的，但許多開(kāi)發人員(yuán)違反了這條規則。

您可能會忘記在這種情況下(xià)編寫的部分(fēn)邏輯，從而導緻代碼注釋質量降低。如果您在單個拉取請求上工(gōng)作多天，最好在完成功能或模塊時寫注釋。

代碼評論是一(yī)門藝術嗎(ma)？

如果您關心代碼質量，請花時間編寫有意義的代碼注釋。這需要一(yī)些練習，但可以很快學會。要記住的關鍵概念是在代碼注釋中(zhōng)添加上下(xià)文。描述你創建代碼背後的原因，而不僅僅是表面的信息。

請記住使您的代碼注釋盡可能簡潔。