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

所以，您應(yīng)該編寫(xiě)代碼注釋來(lái)幫助其他開(kāi)發(fā)人員去理解你所寫(xiě)的代碼。描述函數(shù)、函數(shù)背后的推理及其輸入和輸出的代碼注釋將加快其他開(kāi)發(fā)人員的學(xué)習(xí)過(guò)程。特別是對(duì)于初級(jí)開(kāi)發(fā)人員，這些信息在學(xué)習(xí)代碼時(shí)會(huì)派上用場(chǎng)。

讓我們來(lái)看看不同類(lèi)型的代碼注釋。

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

2. 函數(shù)注釋——函數(shù)注釋是最有用的注釋類(lèi)型，可以自動(dòng)生成多種語(yǔ)言。它們描述了函數(shù)的用途、它接受的參數(shù)以及它生成的輸出。通常只描述公共函數(shù)就足夠了，因?yàn)槭褂媚拇a的開(kāi)發(fā)人員不會(huì)與私有函數(shù)交互。

?3.邏輯注釋 - 邏輯注釋是函數(shù)內(nèi)的注釋?zhuān)糜陉U明復(fù)雜的代碼路徑。

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

代碼注釋?zhuān)? 個(gè)最佳實(shí)踐

這是代碼注釋的四個(gè)最佳實(shí)踐的列表。

1.利用代碼注釋或標(biāo)簽

許多編程語(yǔ)言定義了代碼注釋標(biāo)準(zhǔn)。 Java 使用 Javadoc，而 JavaScript 使用許多文檔生成工具支持的 JSDoc 代碼注釋系統(tǒng)。

您應(yīng)該做好以下代碼標(biāo)記：

@desc - 為您的函數(shù)寫(xiě)下描述

@param - 描述函數(shù)接受的所有輸入?yún)?shù)。確保定義輸入類(lèi)型。

@returns - 描述返回的輸出。確保定義輸出類(lèi)型。

@throws - 描述函數(shù)可以?huà)伋龅腻e(cuò)誤類(lèi)型

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

2. 寫(xiě)下你為什么要做某事

許多開(kāi)發(fā)人員使用注釋來(lái)描述他們的代碼正在做什么。這不一定是錯(cuò)誤的。但是，不要忘記包括創(chuàng)建特定功能或組件的原因。此信息稱(chēng)為上下文。上下文對(duì)于讓開(kāi)發(fā)人員更深入地了解功能或組件背后的設(shè)計(jì)決策至關(guān)重要。當(dāng)其他開(kāi)發(fā)人員想要對(duì)您的功能或組件進(jìn)行更改時(shí)，此上下文至關(guān)重要。

您經(jīng)常會(huì)看到在函數(shù)描述中使用函數(shù)名稱(chēng)的代碼注釋。

3. 不要參考其他文件或評(píng)論

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

如果你認(rèn)為你需要添加一個(gè)文檔來(lái)闡明代碼的目的，這是錯(cuò)誤代碼的危險(xiǎn)信號(hào)。

4. 在寫(xiě)代碼的同時(shí)寫(xiě)注釋

在編寫(xiě)代碼的同時(shí)編寫(xiě)注釋聽(tīng)起來(lái)是很理所應(yīng)當(dāng)?shù)?，但許多開(kāi)發(fā)人員違反了這條規(guī)則。

您可能會(huì)忘記在這種情況下編寫(xiě)的部分邏輯，從而導(dǎo)致代碼注釋質(zhì)量降低。如果您在單個(gè)拉取請(qǐng)求上工作多天，最好在完成功能或模塊時(shí)寫(xiě)注釋。

代碼評(píng)論是一門(mén)藝術(shù)嗎？

如果您關(guān)心代碼質(zhì)量，請(qǐng)花時(shí)間編寫(xiě)有意義的代碼注釋。這需要一些練習(xí)，但可以很快學(xué)會(huì)。要記住的關(guān)鍵概念是在代碼注釋中添加上下文。描述你創(chuàng)建代碼背后的原因，而不僅僅是表面的信息。

網(wǎng)站題目：如何編寫(xiě)有意義的代碼注釋
新聞來(lái)源：http://www.aaarwkj.com/article46/egoshg.html

成都網(wǎng)站建設(shè)公司_創(chuàng)新互聯(lián)，為您提供網(wǎng)站導(dǎo)航、網(wǎng)站設(shè)計(jì)、網(wǎng)站營(yíng)銷(xiāo)、服務(wù)器托管、搜索引擎優(yōu)化、手機(jī)網(wǎng)站建設(shè)

廣告

聲明：本網(wǎng)站發(fā)布的內(nèi)容（圖片、視頻和文字）以用戶(hù)投稿、用戶(hù)轉(zhuǎn)載內(nèi)容為主，如果涉及侵權(quán)請(qǐng)盡快告知，我們將會(huì)在第一時(shí)間刪除。文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng)，如需處理請(qǐng)聯(lián)系客服。電話(huà)：028-86922220；郵箱：631063699@qq.com。內(nèi)容未經(jīng)允許不得轉(zhuǎn)載，或轉(zhuǎn)載時(shí)需注明來(lái)源： 創(chuàng)新互聯(lián)