剛開始學編程的時候，老師就告訴咱們，註釋很重要，可是一直到如今，也沒有人真正告訴過我要怎麼寫註釋。還有不少人甚至乾脆不寫註釋。因此今天想聊一下到底如何寫註釋。java
提到註釋就讓我想起一個段子：兩個程序員去飯店吃飯，點菜的時候程序員甲說：我要吃宮保雞丁，程序員乙就幫他記。程序員
宮保雞丁
而後程序員甲又說：我不想吃宮保雞丁了，換成地三鮮吧。程序員乙就說好的，而後又幫他記上了。編程
//宮保雞丁
地三鮮
這個段子也從側面反映了程序員們習慣性忽略註釋的事實。段子講完了，下面插播一些正文。微信
註釋不能拯救糟糕的代碼編輯器
首先，我想說的可能和大多數人的觀點相左：儘可能少用註釋！沒錯，儘可能少用。由於註釋是會騙人的，並且時間越長的註釋越容易騙人，由於大部分人在修改代碼的時候都不會去修改註釋。少寫註釋，儘可能用代碼去描述你要作什麼。當你要寫註釋的時候，就要思考一下，別人爲何不能經過代碼理解你想表達什麼。這時你須要嘗試修改代碼，來達到上述目的。函數
// Check to see if the employee is eligible for full benefits
if (employee.flags & HOURLY_FLAG) &&
(employee.age > 65)
看一下這段代碼，若是隻看代碼，能夠理解它要表達什麼嗎？工具
if (employee.isEligibleForFUllBenefits())
花上點時間，把代碼改爲這樣，是否是不用註釋也能夠讀懂了？flex
咱們這裏說盡可能少使用註釋，並非徹底不用註釋，在某些狀況下，咱們須要註釋。那麼什麼樣的註釋纔算是好的註釋呢？spa
法律信息.net
有時，公司代碼規範會要求註明版權和著做權。那麼咱們就應該將這些信息放到源文件的開頭位置。
提供信息的註釋
// Returns an instance of the Responder being tested.
protected abstract Responder responderInstance()
這樣的註釋就是不錯的註釋，給讀者提供了返回值的信息，不過，若是咱們把函數命名爲responderBeingTested，那麼這個註釋也就顯得多餘了。
闡釋
能夠用註釋把某些難以理解的參數或返回值翻譯成可讀的形式。當前，前提是若是這些代碼你沒法修改，好比參數或返回值是標準庫的一部分。這時闡釋就顯得頗有用。舉過來一個栗子。
assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(a.compareTo(b) == -1); // a < b
不過這樣的闡釋也有缺點，那就是它有多是不正確的，咱們須要當心確認其正確性。若是缺失正確性，那麼這樣的闡釋只會起到負面做用。
TODO註釋
TODO註釋是比較經常使用的註釋，能夠在代碼裏添加工做列表，例如，對一個空實現函數添加TODO註釋，就能夠解釋這裏爲何是空實現，以及之後要實現什麼。
公共API的Javadoc
這個也許最使人欣賞的註釋習慣了。不過目前咱們一般用swagger來代替註釋。對swagger感興趣的童鞋能夠戳閱讀原文。
所謂見賢思齊焉，見不賢而內自省也。看完了好的註釋，就要想一想怎麼才能寫出好的註釋；接下來再來看看壞的註釋，看的同時須要多檢討本身，儘可能避免寫出壞的註釋。
自說自話
寫的東西只有本身能看懂，別人都不明白要表達什麼。若是讀代碼時連註釋都看不明白，還有人想看下去嗎。
日誌式註釋
幾乎把代碼的每次修改記錄都寫到註釋裏，也許在那個沒有代碼版本控制工具的遠古時代，這麼作還有必定的意義。可是如今咱們擁有不少健壯的代碼版本控制工具，這樣的註釋也就變得毫無心義。
在代碼里加上本身的簽名也是同樣的道理，咱們均可以經過代碼版本控制工具查看具體的建立者和修改者，而不是隻記住建立者。
註釋掉代碼也是同樣，咱們用版本控制工具能夠輕鬆找回之前的代碼，不須要的代碼能夠直接刪掉，而不是留一個註釋掉的代碼放在那裏。
廢話註釋
/** The day of the month. */
private int dayOfMonth;
我不想多廢話了……
結語
也許文中的觀點和大多數人的思惟相左，可能個人有些觀點是錯的，歡迎你們和我討論註釋到底是否必要。最後若是以爲文章不錯的話就幫忙點個贊或者轉發一下吧。
本文分享自微信公衆號 - 代碼潔癖患者（Jackeyzhe2018）。
若有侵權，請聯繫 support@oschina.cn 刪除。
本文參與「OSC源創計劃」，歡迎正在閱讀的你也加入，一塊兒分享。