版權(quán)聲明：本文為博主原創(chuàng)文章，未經(jīng)博主允許不得轉(zhuǎn)載。

整理自知乎上我的一次回答。http://www.zhihu.com/question/20594192

我的觀(guān)點(diǎn)，只寫(xiě)說(shuō)明性注釋，不寫(xiě)功能性注釋。也就是說(shuō)，注釋W(xué)hy，而不是How和What。

類(lèi)和函數(shù)多寫(xiě)文檔注釋，多少行無(wú)所謂，寫(xiě)在最前面，只要你是注釋的Why。

函數(shù)內(nèi)部，盡量少寫(xiě)注釋。如果你的代碼需要寫(xiě)注釋來(lái)說(shuō)明他的功能，那么這段代碼就需要重構(gòu)，最簡(jiǎn)單的方法，最簡(jiǎn)單的方法：提取函數(shù)。這樣的好處是，函數(shù)名就是注釋。一個(gè)錯(cuò)誤的觀(guān)點(diǎn)就是?注釋是給人看的，程序是給電腦看的。其實(shí)，程序是給人看的，湊巧的是，它居然可以在電腦里運(yùn)行。

《重構(gòu):改善既有代碼的設(shè)計(jì)》一書(shū)寫(xiě)道： 每當(dāng)感覺(jué)需要以注釋來(lái)說(shuō)明點(diǎn)什么的時(shí)候，我們就把需要說(shuō)明的東西寫(xiě)進(jìn)一個(gè)獨(dú)立函數(shù)中，并以其用途（而非實(shí)現(xiàn)手法）命名。 每次我給別人講解「選擇排序」、「插入排序時(shí)」，他們都覺(jué)得太難了，而且?guī)缀趺勘緮?shù)據(jù)結(jié)構(gòu)教科書(shū)都是寫(xiě)了一堆代碼和注釋，這絲毫沒(méi)有降低這個(gè)算法的難度。

如果不寫(xiě)注釋，而寫(xiě)成函數(shù)呢？

偽代碼： array_ordered = []
loop_all_element(array, function(i){
? el = select(array[i+1, array.length])
? push(array_ordered, el)
? ......
})

構(gòu)建一個(gè)有序數(shù)組，初始為空，（ps：空集都是有序集）。

循環(huán)整個(gè)數(shù)組，進(jìn)行如下操作：

從數(shù)組剩下的元素里面選擇最小的（或最大的）

將最小元素放在有序數(shù)組的最后面（或者最前面）

不用我多解釋，你一眼就知道（即使你看不到select函數(shù)，也應(yīng)該看到我加粗了“選擇”二字），這是選擇排序。

插入排序呢？大同小異，我就不詳細(xì)寫(xiě)了。

所以，文檔注釋，多少無(wú)所謂。函數(shù)內(nèi)、類(lèi)內(nèi)注釋，能不寫(xiě)，就不寫(xiě)。

相關(guān)閱讀：千萬(wàn)要避免的五種程序注釋方式

你是否有過(guò)復(fù)查程序時(shí)發(fā)現(xiàn)有些注釋毫無(wú)用處？程序注釋是為了提高代碼的可讀性，為了讓原作者以外的其他開(kāi)發(fā)人員更容易理解這段程序。

我把這些讓人郁悶的注釋方式歸為了五類(lèi)，同時(shí)把寫(xiě)出這些注釋的程序員也歸為了五類(lèi)。我希望讀了這篇文章后你感覺(jué)自己不屬于其中的任何一種類(lèi)型。如果你有興趣的話(huà)可以讀一下另外一篇文章?五種程序員(英文)，和這篇講到的五種程序員對(duì)比一下。

1. 高傲的程序員

[java]?view plaincopy

public?class?Program??

{??

????static?void?Main(string[]?args)??

????{??

????????string?message?=?“Hello?World!”;??//?07/24/2010?Bob??

????????Console.WriteLine(message);?//?07/24/2010?Bob??

????????message?=?“I?am?so?proud?of?this?code!”;?//?07/24/2010?Bob??

????????Console.WriteLine(message);?//?07/24/2010?Bob??

????}??

}??

這種程序員是如此的欣賞自己的程序，以至于不得不在每行代碼上都署上自己的大名。應(yīng)該讓版本控制系統(tǒng)來(lái)提供程序變更的信息，他這樣做一眼看去并不能說(shuō)明誰(shuí)對(duì)這行代碼負(fù)責(zé)。

2. 過(guò)時(shí)的程序員

[java]?view plaincopy

public?class?Program??

{??

????static?void?Main(string[]?args)??

????{??

????????/*?這段程序已經(jīng)不再有用?

?????????*?因?yàn)槲覀儼l(fā)現(xiàn)千年蟲(chóng)問(wèn)題只是一場(chǎng)虛驚?

?????????*?我們的系統(tǒng)不會(huì)恢復(fù)到1/1/1900?*/??

????????//DateTime?today?=?DateTime.Today;??

????????//if?(today?==?new?DateTime(1900,?1,?1))??

????????//{??

????????//????today?=?today.AddYears(100);??

????????//????string?message?=?“The?date?has?been?fixed?for?Y2K.”;??

????????//????Console.WriteLine(message);??

????????//}??

????}??

}??

如果一段程序不再有用（比如廢棄了），那就刪了它吧——不要被幾行沒(méi)用的注釋搞的程序混亂不堪。即使你可能以后重用這段代碼，你也可以使用版本控制系統(tǒng)，用它把你的程序恢復(fù)到以前的樣子。

3. 天真的程序員

[java]?view plaincopy

public?class?Program??

{??

????static?void?Main(string[]?args)??

????{??

????????/*?這個(gè)程序是用來(lái)在屏幕上?

?????????*?循環(huán)打印1百萬(wàn)次”I?Rule!”?

?????????*?每次輸出一行。循環(huán)計(jì)數(shù)?

?????????*?從0開(kāi)始，每次加1。?

?????????*?當(dāng)計(jì)數(shù)器等于1百萬(wàn)時(shí)，?

?????????*?循環(huán)就會(huì)停止運(yùn)行*/??

????????for?(int?i?=?0;?i?<?1000000;?i++)??

????????{??

????????????Console.WriteLine(“I?Rule!”);??

????????}??

????}??

}??

基本的編程語(yǔ)法規(guī)則我們大家都知道——我們不需要“編程入門(mén)”。你不需要浪費(fèi)時(shí)間來(lái)解釋一個(gè)顯而易見(jiàn)的東西，我們更希望知道的是你的程序功能——那是浪費(fèi)空間了。

4. 傳奇的程序員

[java]?view plaincopy

public?class?Program??

{??

????static?void?Main(string[]?args)??

????{??

???????/*?有一天我在大街上的一家星巴克里?

????????*?和銷(xiāo)售部的Jim討論問(wèn)題，他告訴我?

????????*?銷(xiāo)售代表是依據(jù)以下的比例提取傭金的。?

????????*?周五:?25%?

????????*?周三:?15%?

????????*?其它日期:?5%?

????????*?我是否告訴你過(guò)我點(diǎn)了一個(gè)卡拉梅?

????????*?鐵咖啡和兩份的Espresso???

???????*/??

????????double?price?=?5.00;??

????????double?commissionRate;??

????????double?commission;??

????????if?(DateTime.Today.DayOfWeek?==?DayOfWeek.Friday)??

????????{??

????????????commissionRate?=?.25;??

????????}??

????????else?if?(DateTime.Today.DayOfWeek?==?DayOfWeek.Wednesday)??

????????{??

????????????commissionRate?=?.15;??

????????}??

????????else??

????????{??

????????????commissionRate?=?.05;??

????????}??

????????commission?=?price?*?commissionRate;??

????}??

}??

如果你不得不在注釋里寫(xiě)明需求，那也不要提到人名。銷(xiāo)售員Jim很可能在公司里不再是銷(xiāo)售。而且大多數(shù)讀到這段注釋的程序員未必都知道Jim是誰(shuí)。你描述的是實(shí)際情況但跟我們的內(nèi)容不相干，所以就省掉吧。

5. 未來(lái)程序員

[java]?view plaincopy

public?class?Program??

{??

????static?void?Main(string[]?args)??

????{??

???????//TODO:?將來(lái)我會(huì)修復(fù)這個(gè)問(wèn)題?–?07/24/1995?Bob??

???????/*?我知道這個(gè)問(wèn)題很難解決而且?

????????*?我現(xiàn)在依賴(lài)于這個(gè)Contains函數(shù)，但?

????????*?我以后會(huì)用一種更有意義，更?

????????*?優(yōu)雅的方式打印這段代碼。?

????????*?我只是現(xiàn)在沒(méi)時(shí)間。?

???????*/??

???????string?message?=?“An?error?has?occurred”;??

???????if(message.Contains(“error”))??

???????{??

???????????throw?new?Exception(message);??

???????}??

????}??

}??

這種注釋是一種集大成者，它包含了上面所說(shuō)的注釋的所有問(wèn)題。TODO注釋在一個(gè)項(xiàng)目最初的開(kāi)發(fā)階段是非常有用的，但這個(gè)注釋看起來(lái)是在好幾年前的產(chǎn)品程序里的——它證明了程序有問(wèn)題。如果程序有問(wèn)題需要解決，馬上解決，不要拖到日后再解決。

如果你不幸是生成這些類(lèi)型注釋的人，或者你想學(xué)習(xí)注釋用法的最佳實(shí)踐，我推薦你閱讀Steve McConnell寫(xiě)的Code Complete（《代碼大全》）。這是一本我建議程序員必讀的書(shū)籍，CSDN 地址?http://blog.csdn.net/justjavac/article/details/7865418。

http://blog.csdn.net/justjavac/article/details/8767078

總結(jié)

以上是生活随笔為你收集整理的老生常谈：注释怎么写？的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。