老生常談：注釋怎麼寫？

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

整理自知乎上我的一次回答。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)

  ......

})

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

   

2. 循環整個數組，進行如下操作：
3. 從數組剩下的元素裡面選擇最小的（或最大的）
4. 将最小元素放在有序數組的最後面（或者最前面）

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

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

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

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

你是否有過複查程式時發現有些注釋毫無用處？程式注釋是為了提高代碼的可讀性，

為了讓原作者以外的其他開發人員更容易了解這段程式。

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

1. 高傲的程式員

[java]  view plain  copy

1. public class Program  
2. {  
3.     static void Main(string[] args)  
4.     {  
5.         string message = “Hello World!”;  // 07/24/2010 Bob  
6.         Console.WriteLine(message); // 07/24/2010 Bob  
7.         message = “I am so proud of this code!”; // 07/24/2010 Bob  
8.         Console.WriteLine(message); // 07/24/2010 Bob  
9.     }  
10. }  

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

2. 過時的程式員

[java]  view plain  copy

1. public class Program  
2. {  
3.     static void Main(string[] args)  
4.     {  
5.         //DateTime today = DateTime.Today;  
6.         //if (today == new DateTime(1900, 1, 1))  
7.         //{  
8.         //    today = today.AddYears(100);  
9.         //    string message = “The date has been fixed for Y2K.”;  
10.         //    Console.WriteLine(message);  
11.         //}  
12.     }  
13. }  

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

3. 天真的程式員

[java]  view plain  copy

1. public class Program  
2. {  
3.     static void Main(string[] args)  
4.     {  
5.         for (int i = 0; i < 1000000; i++)  
6.         {  
7.             Console.WriteLine(“I Rule!”);  
8.         }  
9.     }  
10. }  

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

4. 傳奇的程式員

[java]  view plain  copy

1. public class Program  
2. {  
3.     static void Main(string[] args)  
4.     {  
5.         double price = 5.00;  
6.         double commissionRate;  
7.         double commission;  
8.         if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)  
9.         {  
10.             commissionRate = .25;  
11.         }  
12.         else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)  
13.         {  
14.             commissionRate = .15;  
15.         }  
16.         else  
17.         {  
18.             commissionRate = .05;  
19.         }  
20.         commission = price * commissionRate;  
21.     }  
22. }  

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

5. 未來程式員

[java]  view plain  copy

1. public class Program  
2. {  
3.     static void Main(string[] args)  
4.     {  
5.        //TODO: 将來我會修複這個問題 – 07/24/1995 Bob  
6.        string message = “An error has occurred”;  
7.        if(message.Contains(“error”))  
8.        {  
9.            throw new Exception(message);  
10.        }  
11.     }  
12. }  

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

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

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