提高代碼可讀性的十大注釋技巧分享
本文講述了提高代碼可讀性的十大注釋技巧。分享給大家供大家參考,具體如下:
很多程序員在寫代碼的時候往往都不注意代碼的可讀性,讓別人在閱讀代碼時花費更多的時間。其實,只要程序員在寫代碼的時候,注意為代碼加注釋,并以合理的格式為代碼加注釋,這樣就方便別人查看代碼,也方便自己以后查看了。下面分享十個加注釋的技巧:
1. 逐層注釋
為每個代碼塊添加注釋,并在每一層使用統(tǒng)一的注釋方法和風(fēng)格。例如:
針對每個類:包括摘要信息、作者信息、以及最近修改日期等;
針對每個方法:包括用途、功能、參數(shù)和返回值等。
在團隊工作中,采用標(biāo)準(zhǔn)化的注釋尤為重要。當(dāng)然,使用注釋規(guī)范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推動注釋工作完成得更好。
2. 使用分段注釋
如果有多個代碼塊,而每個代碼塊完成一個單一任務(wù),則在每個代碼塊前添加一個注釋來向讀者說明這段代碼的功能。例子如下:
// Check that all data records // are correct foreach (Record record in records) { if (rec.checkStatus()==Status.OK) { . . . } } // Now we begin to perform // transactions Context ctx = new ApplicationContext(); ctx.BeginTransaction(); . . .
3. 在代碼行后添加注釋
如果多行代碼的每行都要添加注釋,則在每行代碼后添加該行的注釋,這將很容易理解。例如:
const MAX_ITEMS = 10; // maximum number of packets const MASK = 0x1F; // mask bit TCP
在分隔代碼和注釋時,有的開發(fā)者使用tab鍵,而另一些則使用空格鍵。然而由于tab鍵在各編輯器和IDE工具之間的表現(xiàn)不一致,因此最好的方法還是使用空格鍵。
4. 不要侮辱讀者的智慧
避免以下顯而易見的注釋:寫這些無用的注釋會浪費你的時間,并將轉(zhuǎn)移讀者對該代碼細(xì)節(jié)的理解。
if (a == 5) // if a equals 5 counter = 0; // set the counter to zero
5. 禮貌點
避免粗魯?shù)淖⑨?,如:“注意,愚蠢的使用者才會輸入一個負(fù)數(shù)”或“剛修復(fù)的這個問題出于最初的無能開發(fā)者之手”。這樣的注釋能夠反映到它的作者是多么的拙劣,你也永遠(yuǎn)不知道誰將會閱讀這些注釋,可能是:你的老板,客戶,或者是你剛才侮辱過的無能開發(fā)者。
6. 關(guān)注要點
不要寫過多的需要轉(zhuǎn)意且不易理解的注釋。避免ASCII藝術(shù),搞笑,詩情畫意,hyperverbosity的注釋。簡而言之,保持注釋簡單直接。
7. 使用一致的注釋風(fēng)格
一些人堅信注釋應(yīng)該寫到能被非編程者理解的程度。而其他的人則認(rèn)為注釋只要能被開發(fā)人員理解就行了。無論如何,Successful Strategies for Commenting Code已經(jīng)規(guī)定和闡述了注釋的一致性和針對的讀者。就個人而言,我懷疑大部分非編程人員將會去閱讀代碼,因此注釋應(yīng)該是針對其他的開發(fā)者而言。
8. 使用特有的標(biāo)簽
在一個團隊工作中工作時,為了便于與其它程序員溝通,應(yīng)該采用一致的標(biāo)簽集進行注釋。例如,在很多團隊中用TODO標(biāo)簽表示該代碼段還需要額外的工作。
int Estimate(int x, int y) { // TODO: implement the calculations return 0; }
注釋標(biāo)簽切忌不要用于解釋代碼,它只是引起注意或傳遞信息。如果你使用這個技巧,記得追蹤并確認(rèn)這些信息所表示的是什么。
9. 在代碼時添加注釋
在寫代碼時就添加注釋,這時在你腦海里的是清晰完整的思路。如果在代碼最后再添加同樣注釋,它將多花費你一倍的時間。而“我沒有時間寫注釋”,“我很忙”和“項目已經(jīng)延期了”這都是不愿寫注釋而找的借口。一些開發(fā)者覺得應(yīng)該write comments before code,用于理清頭緒。例如:
public void ProcessOrder() { // Make sure the products are available // Check that the customer is valid // Send the order to the store // Generate bill }
10. 為自己注釋代碼
當(dāng)注釋代碼時,要考慮到不僅將來維護你代碼的開發(fā)人員要看,而且你自己也可能要看。用Phil Haack大師的話來說就是:“一旦一行代碼顯示屏幕上,你也就成了這段代碼的維護者”。因此,對于我們寫得好(差)的注釋而言,我們將是第一個受益者(受害者)。
- 高質(zhì)量PHP代碼的50個實用技巧必備(下)
- 高質(zhì)量PHP代碼的50個實用技巧必備(上)
- WordPress開發(fā)中短代碼的實現(xiàn)及相關(guān)函數(shù)使用技巧
- PHP代碼優(yōu)化技巧小結(jié)
- Ruby的25個編程細(xì)節(jié)(技巧、實用代碼段)
- 60個很實用的jQuery代碼開發(fā)技巧收集
- 30個經(jīng)典的jQuery代碼開發(fā)技巧
- 讓代碼整潔、過程清晰的BASH Shell編程技巧
- 編寫高效jQuery代碼的4個原則和5個技巧
- JavaScript避免代碼的重復(fù)執(zhí)行經(jīng)驗技巧分享
- css代碼優(yōu)化的12個技巧
- 優(yōu)化PHP代碼技巧的小結(jié)
相關(guān)文章
git克隆遠(yuǎn)程倉庫的指定分支方法(附常用git配置命令)
這篇文章主要介紹了git克隆遠(yuǎn)程倉庫的指定分支方法(附常用git配置命令),文中通過示例代碼介紹的非常詳細(xì),對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2020-07-07代碼中到底應(yīng)不應(yīng)當(dāng)寫注釋?
注釋的確有其用途,但大部分情況下,程序員在濫用注釋。我是反對夾雜在代碼間的注釋的,我認(rèn)為注釋應(yīng)當(dāng)從代碼中獨立出來——通常被稱為文檔。2014-10-10chatGPT使用及注冊過程中常見的一些錯誤解決方法(所有報錯匯總)
這篇文章主要介紹了chatGPT注冊報錯及使用過程中報錯匯總及解決方法,本文給大家介紹的非常詳細(xì),對大家的學(xué)習(xí)或工作具有一定的參考借鑒價值,需要的朋友可以參考下2023-02-02IDEA2019.3在Plugins中搜索不到translation的解決
這篇文章主要介紹了IDEA2019.3在Plugins中搜索不到translation的解決,文中通過圖文的非常詳細(xì),對大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2020-06-06詳解scratch3.0二次開發(fā)之scratch-blocks中的blocks的類型、定義和使用方法
scratch-blocks是scratch-gui依賴的一個基本模塊,blocks的作用是通過拖曳的方法組成blocks堆塊,今天通過本文給大家分享scratch3.0二次開發(fā)之scratch-blocks的免編譯修改方法,感興趣的朋友一起看看吧2021-08-08