建站
咨詢
售后
建站咨詢
新聞中心
這里有您想知道的互聯(lián)網(wǎng)營銷解決方案
如何編寫有意義的代碼注釋
在大多數(shù)情況下，您并不是唯一在同一項(xiàng)目或代碼庫上工作的人。這意味著其他人可能也會閱讀您的代碼并且必須理解它。
所以，您應(yīng)該編寫代碼注釋來幫助其他開發(fā)人員去理解你所寫的代碼。描述函數(shù)、函數(shù)背后的推理及其輸入和輸出的代碼注釋將加快其他開發(fā)人員的學(xué)習(xí)過程。特別是對于初級開發(fā)人員，這些信息在學(xué)習(xí)代碼時(shí)會派上用場。
讓我們來看看不同類型的代碼注釋。
1. 文檔注釋——這些注釋的主要目的是快速闡明文件或組件的用途。您可以在 `index` 文件的頂部寫一個代碼注釋來解釋組件的作用，而不是閱讀組件的整個代碼來了解它的作用。
2. 函數(shù)注釋——函數(shù)注釋是最有用的注釋類型，可以自動生成多種語言。它們描述了函數(shù)的用途、它接受的參數(shù)以及它生成的輸出。通常只描述公共函數(shù)就足夠了，因?yàn)槭褂媚拇a的開發(fā)人員不會與私有函數(shù)交互。
?3.邏輯注釋 - 邏輯注釋是函數(shù)內(nèi)的注釋，用于闡明復(fù)雜的代碼路徑。
最重要的是，邏輯注釋通常會提供很多詳細(xì)的信息。詳細(xì)程度會造成更多混亂并降低代碼的可讀性。
代碼注釋：4 個最佳實(shí)踐
這是代碼注釋的四個最佳實(shí)踐的列表。
1.利用代碼注釋或標(biāo)簽
許多編程語言定義了代碼注釋標(biāo)準(zhǔn)。 Java 使用 Javadoc，而 JavaScript 使用許多文檔生成工具支持的 JSDoc 代碼注釋系統(tǒng)。
您應(yīng)該做好以下代碼標(biāo)記：
@desc - 為您的函數(shù)寫下描述
@param - 描述函數(shù)接受的所有輸入?yún)?shù)。確保定義輸入類型。
@returns - 描述返回的輸出。確保定義輸出類型。
@throws - 描述函數(shù)可以拋出的錯誤類型
@example - 包含一個或多個顯示輸入和預(yù)期輸出的示例。
2. 寫下你為什么要做某事
許多開發(fā)人員使用注釋來描述他們的代碼正在做什么。這不一定是錯誤的。但是，不要忘記包括創(chuàng)建特定功能或組件的原因。此信息稱為上下文。上下文對于讓開發(fā)人員更深入地了解功能或組件背后的設(shè)計(jì)決策至關(guān)重要。當(dāng)其他開發(fā)人員想要對您的功能或組件進(jìn)行更改時(shí)，此上下文至關(guān)重要。
您經(jīng)常會看到在函數(shù)描述中使用函數(shù)名稱的代碼注釋。
3. 不要參考其他文件或評論
參考闡明功能或組件的其他代碼注釋或內(nèi)部文檔并不是一個好主意。如果開發(fā)者想快速掃描代碼以獲得更好的理解，代碼注釋應(yīng)該清晰。
如果你認(rèn)為你需要添加一個文檔來闡明代碼的目的，這是錯誤代碼的危險(xiǎn)信號。
4. 在寫代碼的同時(shí)寫注釋
在編寫代碼的同時(shí)編寫注釋聽起來是很理所應(yīng)當(dāng)?shù)模S多開發(fā)人員違反了這條規(guī)則。
您可能會忘記在這種情況下編寫的部分邏輯，從而導(dǎo)致代碼注釋質(zhì)量降低。如果您在單個拉取請求上工作多天，最好在完成功能或模塊時(shí)寫注釋。
代碼評論是一門藝術(shù)嗎？
如果您關(guān)心代碼質(zhì)量，請花時(shí)間編寫有意義的代碼注釋。這需要一些練習(xí)，但可以很快學(xué)會。要記住的關(guān)鍵概念是在代碼注釋中添加上下文。描述你創(chuàng)建代碼背后的原因，而不僅僅是表面的信息。
名稱欄目：如何編寫有意義的代碼注釋
轉(zhuǎn)載源于：http://fisionsoft.com.cn/article/egoshg.html
所以，您應(yīng)該編寫代碼注釋來幫助其他開發(fā)人員去理解你所寫的代碼。描述函數(shù)、函數(shù)背后的推理及其輸入和輸出的代碼注釋將加快其他開發(fā)人員的學(xué)習(xí)過程。特別是對于初級開發(fā)人員，這些信息在學(xué)習(xí)代碼時(shí)會派上用場。
讓我們來看看不同類型的代碼注釋。
1. 文檔注釋——這些注釋的主要目的是快速闡明文件或組件的用途。您可以在 `index` 文件的頂部寫一個代碼注釋來解釋組件的作用，而不是閱讀組件的整個代碼來了解它的作用。
2. 函數(shù)注釋——函數(shù)注釋是最有用的注釋類型，可以自動生成多種語言。它們描述了函數(shù)的用途、它接受的參數(shù)以及它生成的輸出。通常只描述公共函數(shù)就足夠了，因?yàn)槭褂媚拇a的開發(fā)人員不會與私有函數(shù)交互。
?3.邏輯注釋 - 邏輯注釋是函數(shù)內(nèi)的注釋，用于闡明復(fù)雜的代碼路徑。
最重要的是，邏輯注釋通常會提供很多詳細(xì)的信息。詳細(xì)程度會造成更多混亂并降低代碼的可讀性。
代碼注釋：4 個最佳實(shí)踐
這是代碼注釋的四個最佳實(shí)踐的列表。
1.利用代碼注釋或標(biāo)簽
許多編程語言定義了代碼注釋標(biāo)準(zhǔn)。 Java 使用 Javadoc，而 JavaScript 使用許多文檔生成工具支持的 JSDoc 代碼注釋系統(tǒng)。
您應(yīng)該做好以下代碼標(biāo)記：
@desc - 為您的函數(shù)寫下描述
@param - 描述函數(shù)接受的所有輸入?yún)?shù)。確保定義輸入類型。
@returns - 描述返回的輸出。確保定義輸出類型。
@throws - 描述函數(shù)可以拋出的錯誤類型
@example - 包含一個或多個顯示輸入和預(yù)期輸出的示例。
2. 寫下你為什么要做某事
許多開發(fā)人員使用注釋來描述他們的代碼正在做什么。這不一定是錯誤的。但是，不要忘記包括創(chuàng)建特定功能或組件的原因。此信息稱為上下文。上下文對于讓開發(fā)人員更深入地了解功能或組件背后的設(shè)計(jì)決策至關(guān)重要。當(dāng)其他開發(fā)人員想要對您的功能或組件進(jìn)行更改時(shí)，此上下文至關(guān)重要。
您經(jīng)常會看到在函數(shù)描述中使用函數(shù)名稱的代碼注釋。
3. 不要參考其他文件或評論
參考闡明功能或組件的其他代碼注釋或內(nèi)部文檔并不是一個好主意。如果開發(fā)者想快速掃描代碼以獲得更好的理解，代碼注釋應(yīng)該清晰。
如果你認(rèn)為你需要添加一個文檔來闡明代碼的目的，這是錯誤代碼的危險(xiǎn)信號。
4. 在寫代碼的同時(shí)寫注釋
在編寫代碼的同時(shí)編寫注釋聽起來是很理所應(yīng)當(dāng)?shù)模S多開發(fā)人員違反了這條規(guī)則。
您可能會忘記在這種情況下編寫的部分邏輯，從而導(dǎo)致代碼注釋質(zhì)量降低。如果您在單個拉取請求上工作多天，最好在完成功能或模塊時(shí)寫注釋。
代碼評論是一門藝術(shù)嗎？
如果您關(guān)心代碼質(zhì)量，請花時(shí)間編寫有意義的代碼注釋。這需要一些練習(xí)，但可以很快學(xué)會。要記住的關(guān)鍵概念是在代碼注釋中添加上下文。描述你創(chuàng)建代碼背后的原因，而不僅僅是表面的信息。
名稱欄目：如何編寫有意義的代碼注釋
轉(zhuǎn)載源于：http://fisionsoft.com.cn/article/egoshg.html
