版權聲明：本文為部落客原創文章，未經部落客允許不得轉載。
整理自知乎上我的一次回答。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 plain copy
- 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 plain copy
- public class Program
- {
- static void Main(string[] args)
- {
- //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 plain copy
- public class Program
- {
- static void Main(string[] args)
- {
- for (int i = 0; i < 1000000; i++)
- {
- Console.WriteLine(“I Rule!”);
- }
- }
- }
基本的程式設計文法規則我們大家都知道——我們不需要“程式設計入門”。你不需要浪費時間來解釋一個顯而易見的東西，我們更希望知道的是你的程式功能——那是浪費空間了。
4. 傳奇的程式員
[java] view plain copy
- public class Program
- {
- static void Main(string[] args)
- {
- 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 plain copy
- public class Program
- {
- static void Main(string[] args)
- {
- //TODO: 将來我會修複這個問題 – 07/24/1995 Bob
- 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