註解

註解

不要替糟糕的程式碼寫註解－－重寫它

寫註解就代表失敗了!!

代表著我們沒有能力用程式碼去表達我們的意圖。

使用註解並不值得慶賀。

當註解存在的越久，就越容易偏離事實，甚至可能完全就是在誤導、說謊。

但是程式碼不會說謊，所以與其相信註解，不如直接去看程式碼。

與其花時間去為自己雜亂的程式碼寫註解，不如好好的花時間去處理那團程式碼。

有益型的註解

法律型的註解

像這樣的註解，內容不應該直接是法律條文，應該讓註解去參考一個標準的許可或其他外部文件，會比直接將所有條款列在註解內有用得多。

資訊型的註解

提供一些基本資訊，例如說明一個抽象方法的回傳值，但如果可能的話，利用函式名稱去傳達訊息會是更好的選擇。

//Returns an instance of the Responder being tested.
protected abstract responder responderInstance();

改成

responderBeingTested();

就可以將註解省去。

對意圖的解釋

有時候，註解不僅提供關於實作的有用資訊，也提供某個決定背後的意圖。

有時你可能不同意程式設計師對這個問題的解法，但你可以了解他想要做什麼。

闡明

有時候註解把難解的參數或回傳值翻譯成具有可讀性的文字，這種註解是有幫助的。

但要十分注意，萬一闡明性的註解並不正確，那就帶著相當大的風險。

請想想是否沒有其他辦法了才這麼做，並加倍注意註解的正確性。

對後果的告誡

TODO(代辦事項)註解

放大重要性

公共API裡的Javadoc

糟糕的註解

喃喃自語

多餘的註解

誤導型註解

規定型註解

日誌型註解

如今有版本控制系統可以幫助我們做這件事情，應該徹底移除此類註解。

干擾型註解

當可以使用函式或變數表達訊息時，就別使用註解

位置的標誌物

只有極少的特殊情況下，利用這樣的橫幅來聚集特定函式，才是合理的行為。

倘若太多這樣的橫幅，只會變成一種讓人忽略的凌亂物。應該被移除!

右大括號的註解

程式太長且有深層巢狀時，才會是有意義的。

但倘若發生這樣的狀況，想辦法精簡程式碼吧!

被註解的程式碼

勇敢的刪除吧! 現今已經有偉大的版本控制系統了!

HTML形式的註解

非區域性的註解

過多的資訊

不顯著的關聯

倘若連註解本身都需要額外的解釋，那這個註解有點太慘。

函式的標頭

直接把命名取好，解決它!

非公共程式碼裡的Javadoc