# 第四章 註解

###### tags: `Tag(Clean Code)`

[TOC]

## 大綱

「不要替糟糕的程式碼寫註解」-- 布萊恩.格尼漢 & 普勞賀

寫註解得==動機==很重要，不要試圖解釋也不要為糟糕的程式碼寫註解，當多人維護或寫改演化後此註解只會提供錯誤資訊。

用程式碼表達你的本意，如果程式碼有足夠表達能力，就可以不寫註解。不準確得註解，遠比沒有註解還糟糕。

主要分為三類：

1. 必要註解
2. 無用註解
3. 反作用註解

---

#### 用程式碼表達你的本意

第一種

// Check to see if the employee is eligible for full benefits
if (employee.flags & HOURLY_FLAG) && (employee.age > 65)

第二種
`if employee.isEligibleForFullBenefits()`

說明：
第一種為使用註解說明
第二種是透過==函式命名==更能夠清楚表達程式碼的意圖

心得：
撰寫程式時，沒有必要為一件非常簡單的事情抽離原本的程式為一個新的函式，如果每一件事都必須這樣做，只會徒增閱讀上的痛苦

---

## 有益的註解(必要註解)

#### 1. 法律信息
公司規範限定的需要在代碼信息中加入相對應的法律信息， 比如版本或者著作權的聲明。


#### 2. 闡述
方法本身俱備一定的複雜性， 對於調用方來講並不需要過多的了解內部的細節， 或者對該方法的方案選擇進行原有的解釋。


#### 3. TODO(代辦事項)
方法中存在一些疏漏， 但對於當前方案沒有影響。或者對部分細節可以進行再優化， 在代碼上進行標註以提醒自己完成相關的功能。

#### 4. 公共API 的JavaDoc
良好描述的公共API 可以避免使用方關注實現細節， 只需要輸入合規的參數， 即可得到對應的結果。比如標準JAVA 庫中的JavaDoc文檔。


總結：
註解是很重要的一個環節，程式碼無法只用命名以及函式表達其目的時，就得撰寫註解幫助我們理解程式碼的邏輯。但是，如果程式碼本身就能清楚表達邏輯時，註解就不是必要的一環。寫之前確認是否註解都是有益的，或者只是干擾型的註解。

---

## 糟糕的註解(無用註釋)

#### 代碼簡單， 冗餘註釋
應避免喃喃自語的、多餘的與程式無關的註解。
代碼本身的邏輯比較簡單， 沒必要進行冗餘的註釋來解釋方法或者變量的意義。


#### 規定型註釋
每個變量或者方法都進行JavaDoc 的標註或者註釋是沒有必要的， 除了增加無用的代碼行數。


#### 日誌型註解
針對每次代碼的變動而註釋對應的改動內容， 現在可以完全由Git 版本控制工具來完成。


#### 註釋掉的代碼
對於項目工程中已經註釋掉的代碼， 不要考慮將來是否會引用，移除掉它。不用擔心會丟失這部分數據， 因為都會記錄到版本工具中， 已經註釋掉的代碼會破壞代碼的閱讀性。

## 反作用註釋

#### 誘導性描述
除了一些本身就存在錯誤的描述會帶來困擾之外， 即便一些開始準確無比的描述， 在後期功能的修改演化中也可能會遺漏掉描述的準確性，將會對後續的開發進行誤導。