版權聲明：本文為博主原創文章，未經博主允許不得轉載。

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

我的觀點，只寫說明性注釋，不寫功能性注釋。也就是說，注釋Why，而不是How和What。

類和函數多寫文檔注釋，多少行無所謂，寫在最前面，只要你是注釋的Why。

函數內部，盡量少寫注釋。如果你的代碼需要寫注釋來說明他的功能，那么這段代碼就需要重構，最簡單的方法，最簡單的方法：提取函數。這樣的好處是，函數名就是注釋。一個錯誤的觀點就是?注釋是給人看的，程序是給電腦看的。其實，程序是給人看的，湊巧的是，它居然可以在電腦里運行。

《重構:改善既有代碼的設計》一書寫道： 每當感覺需要以注釋來說明點什么的時候，我們就把需要說明的東西寫進一個獨立函數中，并以其用途（而非實現手法）命名。 每次我給別人講解「選擇排序」、「插入排序時」，他們都覺得太難了，而且幾乎每本數據結構教科書都是寫了一堆代碼和注釋，這絲毫沒有降低這個算法的難度。

如果不寫注釋，而寫成函數呢？

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

構建一個有序數組，初始為空，（ps：空集都是有序集）。

循環整個數組，進行如下操作：

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

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

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

插入排序呢？大同小異，我就不詳細寫了。

所以，文檔注釋，多少無所謂。函數內、類內注釋，能不寫，就不寫。

相關閱讀：千萬要避免的五種程序注釋方式

你是否有過復查程序時發現有些注釋毫無用處？程序注釋是為了提高代碼的可讀性，為了讓原作者以外的其他開發人員更容易理解這段程序。

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

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

????}??

}??

這種程序員是如此的欣賞自己的程序，以至于不得不在每行代碼上都署上自己的大名。應該讓版本控制系統來提供程序變更的信息，他這樣做一眼看去并不能說明誰對這行代碼負責。

2. 過時的程序員

[java]?view plaincopy

public?class?Program??

{??

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

????{??

????????/*?這段程序已經不再有用?

?????????*?因為我們發現千年蟲問題只是一場虛驚?

?????????*?我們的系統不會恢復到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);??

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

????}??

}??

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

3. 天真的程序員

[java]?view plaincopy

public?class?Program??

{??

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

????{??

????????/*?這個程序是用來在屏幕上?

?????????*?循環打印1百萬次”I?Rule!”?

?????????*?每次輸出一行。循環計數?

?????????*?從0開始，每次加1。?

?????????*?當計數器等于1百萬時，?

?????????*?循環就會停止運行*/??

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

????????{??

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

????????}??

????}??

}??

基本的編程語法規則我們大家都知道——我們不需要“編程入門”。你不需要浪費時間來解釋一個顯而易見的東西，我們更希望知道的是你的程序功能——那是浪費空間了。

4. 傳奇的程序員

[java]?view plaincopy

public?class?Program??

{??

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

????{??

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

????????*?和銷售部的Jim討論問題，他告訴我?

????????*?銷售代表是依據以下的比例提取傭金的。?

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

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

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

????????*?我是否告訴你過我點了一個卡拉梅?

????????*?鐵咖啡和兩份的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;??

????}??

}??

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

5. 未來程序員

[java]?view plaincopy

public?class?Program??

{??

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

????{??

???????//TODO:?將來我會修復這個問題?–?07/24/1995?Bob??

???????/*?我知道這個問題很難解決而且?

????????*?我現在依賴于這個Contains函數，但?

????????*?我以后會用一種更有意義，更?

????????*?優雅的方式打印這段代碼。?

????????*?我只是現在沒時間。?

???????*/??

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

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

???????{??

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

???????}??

????}??

}??

這種注釋是一種集大成者，它包含了上面所說的注釋的所有問題。TODO注釋在一個項目最初的開發階段是非常有用的，但這個注釋看起來是在好幾年前的產品程序里的——它證明了程序有問題。如果程序有問題需要解決，馬上解決，不要拖到日后再解決。

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

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

總結

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

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。