老生常谈：注释怎么写？
版權聲明：本文為博主原創文章，未經博主允許不得轉載。
整理自知乎上我的一次回答。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. 高傲的程序員
[java]?view plaincopy這種程序員是如此的欣賞自己的程序，以至于不得不在每行代碼上都署上自己的大名。應該讓版本控制系統來提供程序變更的信息，他這樣做一眼看去并不能說明誰對這行代碼負責。
2. 過時的程序員
[java]?view plaincopy如果一段程序不再有用（比如廢棄了），那就刪了它吧——不要被幾行沒用的注釋搞的程序混亂不堪。即使你可能以后重用這段代碼，你也可以使用版本控制系統，用它把你的程序恢復到以前的樣子。
3. 天真的程序員
[java]?view plaincopy基本的編程語法規則我們大家都知道——我們不需要“編程入門”。你不需要浪費時間來解釋一個顯而易見的東西，我們更希望知道的是你的程序功能——那是浪費空間了。
4. 傳奇的程序員
[java]?view plaincopy如果你不得不在注釋里寫明需求，那也不要提到人名。銷售員Jim很可能在公司里不再是銷售。而且大多數讀到這段注釋的程序員未必都知道Jim是誰。你描述的是實際情況但跟我們的內容不相干，所以就省掉吧。
5. 未來程序員
[java]?view plaincopy這種注釋是一種集大成者，它包含了上面所說的注釋的所有問題。TODO注釋在一個項目最初的開發階段是非常有用的，但這個注釋看起來是在好幾年前的產品程序里的——它證明了程序有問題。如果程序有問題需要解決，馬上解決，不要拖到日后再解決。
如果你不幸是生成這些類型注釋的人，或者你想學習注釋用法的最佳實踐，我推薦你閱讀Steve McConnell寫的Code Complete（《代碼大全》）。這是一本我建議程序員必讀的書籍，CSDN 地址?http://blog.csdn.net/justjavac/article/details/7865418。
http://blog.csdn.net/justjavac/article/details/8767078總結
以上是生活随笔為你收集整理的老生常谈：注释怎么写？的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 机器学习部分国内牛人
- 下一篇： 为什么数组是从0开始的