如何寫出優秀的代碼注釋？

01-14

有哪些技巧可以幫助程序員寫出優秀的注釋，對提高工作效率有幫助。
（本人在學習Java和C++，希望能以此為語言進行說明）

樓上的某些同學真的知道什麼叫優秀的代碼注釋？？？

↑↑↑ 這才是注釋的精髓！根本不需要看代碼，你就能明白這個類是幹嘛的！

很早以前，我聽說寫代碼要寫注釋，甚至有聽說代碼的20%是注釋，那時我就天天認真的寫注釋，後來看書多了，了解敏捷開發什麼的，知道了好的代碼是不需要注釋這麼一說的，後來我也就不寫注釋了，幾千行代碼裡面都沒幾行注釋。

好的代碼本身就是注釋，這話是對的，但我覺得這僅限於邏輯簡單直白的代碼，寫過多的注釋除了乍看之下能美化下代碼之外沒很多其他的用處，對於邏輯複雜的代碼，如果沒有注釋我相信看代碼的人是要花很多時間精力去理解的，不管你代碼寫的有多好都是如此。邏輯複雜的代碼，我現在覺得是必須要寫注釋的，注釋怎麼寫？對於實現來說，把自己寫代碼時怎麼思考的用精簡的語言寫下來，如果有例子，那就在注釋里寫上例子。對於介面來說，那最好是像敏捷開發說的那樣，代碼介面本身就是注釋，一看就能懂，如果確實做不到一看就能懂，那就加一點注釋描述這個介面是在整個代碼中是處於什麼角色，如果有例子，也把例子寫下。

另外，注釋要優秀，注釋排版必須要好看。

分享一個代碼大全里的方法內注釋的經驗。定好方法聲明（名稱，入參，出參等）後，在方法體內用偽代碼寫出方法流程，注掉。

文檔是文檔，和代碼注釋不是一個東西...

代碼注釋不一定是必須的吧

autotest以及commit message很大程度上就夠了吧？可以看看Qt的

https://github.com/qtproject/qtbase/commits/stable

一般來說，我覺得比較完整的注釋是：

1.如果你的代碼是開源供很多人用的，最好在入口文件的前面，或者是專門有一個readme文件來說明你整個項目的基本結構和功能。

2.如果方便的話，最後給出一個demo來供別人參考

3.方法/類注釋一般來說我會要求寫方法和類的人，在每一個方法/類前面寫上方法的功能，傳入參數和含義，返回的數據結構和含義，方法的作者以及聯繫郵箱和寫入時間。

4.之後每次修改，都要在注釋後面寫上修改者的姓名郵箱時間和修改原因以及修改內容的簡要說明

===================================================================

個人認為，注釋的價值在於：

1.方便別人調用

2.方便別人維護

還有人努力追求寫出優秀的代碼注釋，感動呀，只要人人都獻出一點愛，世界將變成美好的人間呀……

技巧之一是按照一些成熟文檔生成工具的格式寫注釋，比如doxygen之類的。好的注釋配上doxygen可以讓人在非常短的時間內就對程序的總體結構以及不同組件之間的關係獲得一個非常清楚的認識。非常有用，即使是沒有注釋的代碼，用doxygen掃一遍來生成文檔也是一個非常有用的做法。

別的技巧都不是技巧了，都是內功。比如你寫注釋的時候自己一定要對自己軟體的機制了解得很清楚，同時你要對你們那個領域的基本概念也及基本知識了解得很清楚，這樣寫注釋的和讀注釋的能夠在一個比較堅實的基礎上交流。否則就是雞同鴨講，各說各話。

寫注釋是好習慣，不光是為別人，也為自己。畢竟維護自己代碼的，更多的時候還是你自己。請不要相信你的大腦，別以為你肯定明白你自己寫的代碼，三個星期後，代碼是不是你寫的，你就已經分辨不出來了……

介面的注釋要清晰，明確，讓人知道怎麼用。

實現的注釋要撿著重點寫，提醒一下兒實現中應該注意的地方。

設計或實現上的選擇，最好簡單寫一下兒自己都考慮過什麼方案，為什麼選擇了代碼里的那種。

把自己當成代碼的讀者，想像一下兒當你讀到這裡的時候，你最想知道什麼？

我覺得寫注釋最基本的原則是：注釋是用來解釋一段代碼的意圖而不是行為的。

代碼的行為應該可以從代碼本身很容易的看出，如果不明顯，那是代碼寫的有問題，而不是需要添加註釋。

據說最好的注釋是沒有注釋，如果你的類，方法，變數定義夠準確，構造夠完美，那麼注釋其實是多餘的！當然不排除有一些代碼的確是需要那麼一兩行解釋性注釋的。

至於怎麼寫好注釋，請參考《代碼整潔之道》.

《代碼大全》也有這個話題，非常值得一看

1、讓別人看你的代碼，如果看不懂，你需要改進你的注釋，或者需要改進你的代碼邏輯

2、別人看你的代碼，像在看一篇美文（當然是理想狀態）

文檔化

函數，介面的注釋很重要，這個要明確寫清楚。

函數內部的注釋，盡量簡單明了。

分支，循環處的注釋要明確表示開發者的意圖。