欧美bbbwbbbw肥妇,免费乱码人妻系列日韩,一级黄片

提高代碼可讀性的十大注釋技巧分享

 更新時(shí)間:2016年03月03日 11:20:13   作者:彬彬寒靈  
這篇文章主要介紹了提高代碼可讀性的十大注釋技巧,詳細(xì)分析了編程開(kāi)發(fā)中常用的代碼注釋方法,需要的朋友可以參考下

本文講述了提高代碼可讀性的十大注釋技巧。分享給大家供大家參考,具體如下:

很多程序員在寫代碼的時(shí)候往往都不注意代碼的可讀性,讓別人在閱讀代碼時(shí)花費(fèi)更多的時(shí)間。其實(shí),只要程序員在寫代碼的時(shí)候,注意為代碼加注釋,并以合理的格式為代碼加注釋,這樣就方便別人查看代碼,也方便自己以后查看了。下面分享十個(gè)加注釋的技巧:

1. 逐層注釋

為每個(gè)代碼塊添加注釋,并在每一層使用統(tǒng)一的注釋方法和風(fēng)格。例如:

針對(duì)每個(gè)類:包括摘要信息、作者信息、以及最近修改日期等;

針對(duì)每個(gè)方法:包括用途、功能、參數(shù)和返回值等。

在團(tuán)隊(duì)工作中,采用標(biāo)準(zhǔn)化的注釋尤為重要。當(dāng)然,使用注釋規(guī)范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推動(dòng)注釋工作完成得更好。

2. 使用分段注釋

如果有多個(gè)代碼塊,而每個(gè)代碼塊完成一個(gè)單一任務(wù),則在每個(gè)代碼塊前添加一個(gè)注釋來(lái)向讀者說(shuō)明這段代碼的功能。例子如下:

// 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

在分隔代碼和注釋時(shí),有的開(kāi)發(fā)者使用tab鍵,而另一些則使用空格鍵。然而由于tab鍵在各編輯器和IDE工具之間的表現(xiàn)不一致,因此最好的方法還是使用空格鍵。

4. 不要侮辱讀者的智慧

避免以下顯而易見(jiàn)的注釋:寫這些無(wú)用的注釋會(huì)浪費(fèi)你的時(shí)間,并將轉(zhuǎn)移讀者對(duì)該代碼細(xì)節(jié)的理解。

if (a == 5)   // if a equals 5
  counter = 0; // set the counter to zero

5. 禮貌點(diǎn)

避免粗魯?shù)淖⑨?,如:“注意,愚蠢的使用者才?huì)輸入一個(gè)負(fù)數(shù)”或“剛修復(fù)的這個(gè)問(wèn)題出于最初的無(wú)能開(kāi)發(fā)者之手”。這樣的注釋能夠反映到它的作者是多么的拙劣,你也永遠(yuǎn)不知道誰(shuí)將會(huì)閱讀這些注釋,可能是:你的老板,客戶,或者是你剛才侮辱過(guò)的無(wú)能開(kāi)發(fā)者。

6. 關(guān)注要點(diǎn)

不要寫過(guò)多的需要轉(zhuǎn)意且不易理解的注釋。避免ASCII藝術(shù),搞笑,詩(shī)情畫意,hyperverbosity的注釋。簡(jiǎn)而言之,保持注釋簡(jiǎn)單直接。

7. 使用一致的注釋風(fēng)格

一些人堅(jiān)信注釋應(yīng)該寫到能被非編程者理解的程度。而其他的人則認(rèn)為注釋只要能被開(kāi)發(fā)人員理解就行了。無(wú)論如何,Successful Strategies for Commenting Code已經(jīng)規(guī)定和闡述了注釋的一致性和針對(duì)的讀者。就個(gè)人而言,我懷疑大部分非編程人員將會(huì)去閱讀代碼,因此注釋應(yīng)該是針對(duì)其他的開(kāi)發(fā)者而言。

8. 使用特有的標(biāo)簽

在一個(gè)團(tuán)隊(duì)工作中工作時(shí),為了便于與其它程序員溝通,應(yīng)該采用一致的標(biāo)簽集進(jìn)行注釋。例如,在很多團(tuán)隊(duì)中用TODO標(biāo)簽表示該代碼段還需要額外的工作。

int Estimate(int x, int y)
{
  // TODO: implement the calculations
  return 0;
}

注釋標(biāo)簽切忌不要用于解釋代碼,它只是引起注意或傳遞信息。如果你使用這個(gè)技巧,記得追蹤并確認(rèn)這些信息所表示的是什么。

9. 在代碼時(shí)添加注釋

在寫代碼時(shí)就添加注釋,這時(shí)在你腦海里的是清晰完整的思路。如果在代碼最后再添加同樣注釋,它將多花費(fèi)你一倍的時(shí)間。而“我沒(méi)有時(shí)間寫注釋”,“我很忙”和“項(xiàng)目已經(jīng)延期了”這都是不愿寫注釋而找的借口。一些開(kāi)發(fā)者覺(jué)得應(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)注釋代碼時(shí),要考慮到不僅將來(lái)維護(hù)你代碼的開(kāi)發(fā)人員要看,而且你自己也可能要看。用Phil Haack大師的話來(lái)說(shuō)就是:“一旦一行代碼顯示屏幕上,你也就成了這段代碼的維護(hù)者”。因此,對(duì)于我們寫得好(差)的注釋而言,我們將是第一個(gè)受益者(受害者)。

相關(guān)文章

  • 如何讓 vim 成為我們的神器(小結(jié))

    如何讓 vim 成為我們的神器(小結(jié))

    這篇文章主要介紹了如何讓 vim 成為我們的神器(小結(jié)),文中通過(guò)示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧
    2020-10-10
  • git克隆遠(yuǎn)程倉(cāng)庫(kù)的指定分支方法(附常用git配置命令)

    git克隆遠(yuǎn)程倉(cāng)庫(kù)的指定分支方法(附常用git配置命令)

    這篇文章主要介紹了git克隆遠(yuǎn)程倉(cāng)庫(kù)的指定分支方法(附常用git配置命令),文中通過(guò)示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧
    2020-07-07
  • 代碼中到底應(yīng)不應(yīng)當(dāng)寫注釋?

    代碼中到底應(yīng)不應(yīng)當(dāng)寫注釋?

    注釋的確有其用途,但大部分情況下,程序員在濫用注釋。我是反對(duì)夾雜在代碼間的注釋的,我認(rèn)為注釋應(yīng)當(dāng)從代碼中獨(dú)立出來(lái)——通常被稱為文檔。
    2014-10-10
  • chatGPT使用及注冊(cè)過(guò)程中常見(jiàn)的一些錯(cuò)誤解決方法(所有報(bào)錯(cuò)匯總)

    chatGPT使用及注冊(cè)過(guò)程中常見(jiàn)的一些錯(cuò)誤解決方法(所有報(bào)錯(cuò)匯總)

    這篇文章主要介紹了chatGPT注冊(cè)報(bào)錯(cuò)及使用過(guò)程中報(bào)錯(cuò)匯總及解決方法,本文給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下
    2023-02-02
  • IDEA2019.3在Plugins中搜索不到translation的解決

    IDEA2019.3在Plugins中搜索不到translation的解決

    這篇文章主要介紹了IDEA2019.3在Plugins中搜索不到translation的解決,文中通過(guò)圖文的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧
    2020-06-06
  • 詳解scratch3.0二次開(kāi)發(fā)之scratch-blocks中的blocks的類型、定義和使用方法

    詳解scratch3.0二次開(kāi)發(fā)之scratch-blocks中的blocks的類型、定義和使用方法

    scratch-blocks是scratch-gui依賴的一個(gè)基本模塊,blocks的作用是通過(guò)拖曳的方法組成blocks堆塊,今天通過(guò)本文給大家分享scratch3.0二次開(kāi)發(fā)之scratch-blocks的免編譯修改方法,感興趣的朋友一起看看吧
    2021-08-08
  • git在idea中的沖突解決方法(非常重要)

    git在idea中的沖突解決方法(非常重要)

    這篇文章主要介紹了git在idea中的沖突解決,文中通過(guò)示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧
    2020-07-07
  • vsCode中配置setings.json的技巧

    vsCode中配置setings.json的技巧

    本文給大家分享的是一個(gè)在vsCode中配置好的setings.json的樣例,可以給大家一個(gè)參考,有需要的小伙伴可以來(lái)看下
    2020-01-01
  • VsCode的jsconfig配置文件說(shuō)明詳解

    VsCode的jsconfig配置文件說(shuō)明詳解

    這篇文章主要介紹了VsCode的jsconfig配置文件說(shuō)明詳解,文中通過(guò)示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧
    2020-04-04
  • Geohash的原理、算法和具體應(yīng)用探究

    Geohash的原理、算法和具體應(yīng)用探究

    這篇文章主要介紹了Geohash的原理、算法和具體應(yīng)用探究,Geohash可以實(shí)現(xiàn)當(dāng)前手機(jī)應(yīng)用中的查找附近的人功能,需要的朋友可以參考下
    2014-07-07

最新評(píng)論