# 註解

## 註解

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

寫註解就代表失敗了!!

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

使用註解並不值得慶賀。

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

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

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

## 有益型的註解

**法律型的註解**

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

**資訊型的註解**

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

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

改成

```
responderBeingTested();
```

就可以將註解省去。

**對意圖的解釋**

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

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

**闡明**

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

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

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

**對後果的告誡**

**TODO(代辦事項)註解**

**放大重要性**

**公共API裡的Javadoc**

## 糟糕的註解

**喃喃自語**

**多餘的註解**

**誤導型註解**

**規定型註解**

**日誌型註解**

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

**干擾型註解**

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

**位置的標誌物**

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

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

**右大括號的註解**

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

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

**被註解的程式碼**

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

**HTML形式的註解**

**非區域性的註解**

**過多的資訊**

**不顯著的關聯**

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

**函式的標頭**

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

**非公共程式碼裡的Javadoc**
