# 註解

## 不適當的資訊

當註解含有的資訊更適合儲存於原始碼管控系統、錯誤追蹤系統或任何儲存記錄的系統。
例如，程式檔的歷史修改，作者、最後修改日期、效能報告序號之類的詮釋資訊，不應該出現在註解。

## 廢棄的註解

當註解過時、不相關或不正確時，就是一種廢棄的註解。
如果你發現廢棄的註解，最好是儘快更新或移除它。否則容易和它原先描述的程式越離越遠。

## 多餘的註解

如果註解描述了原本程式已經能夠表達的意圖，那麼這段註解就是多餘的。例如：

```java
i++; // increment i
```

另一個「多餘的註解」的例子是有關 Javadoc：

```java
/**
 * @param sellRequest
 * @return
 * @throws ManagedComponentException
 */
public SellRequest beginSellItem(SellRequest sellRequest) throws ManagedComponentException
```

註解應該要說明的是，程式本身無法表達的意圖。

## 寫得不好的程式碼

花一點時間去確保這是你所能寫出的最好註解。
仔細選用你的詞彙，使用正確的文法和標點符號，不要說廢話，不要說某些顯而易見的事，要簡潔有力。

## 被註解掉的程式碼

誰知道這段程式碼多舊了？誰知道這樣的舉動有沒有意義？
當你看到備註解掉的程式，刪掉它！不要擔心，因為程式碼管控系統會幫你記住這段程式碼。

# 開發環境

## 需要多個步驟以建立專案或系統

建立一個專案應該是單一步驟的簡單行為，你不應該還需要從原始碼管控系統一點一點地找出程式片段，你也不應該需要一連串神祕的指令或隨上下文變動的腳本，才能幫你建立個別的元素。

## 需要多個步驟以進行測試

你應該要能用一個指令就可以快速、簡單和直接地執行**所有的**單元測試。

# 函式

## 過多的參數

函式的參數不能太多。沒有參數是最棒的，超過三以上的參數，其必要性是非常值得懷疑的，應該要盡可能避免。

## 輸出型參數

輸出型參數是不直覺的。讀者通常預期參數是用來輸入的，而不是用來輸出結果的。
如果你的函式一定得修改某個東西的狀態，就讓該函式只能修改其所屬物件的狀態。

```java
appendFooter(s);

public void appendFooter(StringBuffer report)
```

這個函式真的是 s 接在某個東西的後方嗎？還是這個函式會把某些頁尾加到 s 的後面？

它如果改成下列方式來呼叫 appendFooter 會比較好。

```java
report.appendFooter();
```

## 旗標參數

Boolean 參數大聲地說出「該函式做了超過一件的任務」，應該被移除。

## 被遺棄的函式

不要害怕刪掉那些不再被呼叫的函式。記住，你的原始碼管控系統還會記住這些函式。

# 一般狀況

## 同份原始檔存在多種語言

在現今的程式開發環境中，屎有可能將許多不同的語言放置在同一份原始檔裡。例如，一個 Java 原始檔可能包含了 XML、HTML、YAML、JavaDoc 之類的片段。
對於原始碼來說，最理想的狀態是只擁有一種，而且是唯一的一種語言。

## 明顯該有的行為未被實現

遵循「最少驚奇原則」，任何函式或類別應該實現其他程式設計師合理預期該有的行為，例如，考慮一個函式可將某日子的名稱，翻譯成一個代表該日子的列舉值。

```java
Day day = DayDate.StringToDay(String dayName);
```

我們期待字串 Monday 會被翻譯成 `Day.MONDAY`。我們也會期待一些常用的星期縮寫也能夠被翻譯。
當一個明顯該有的行為沒有被實現，程式碼的讀者和程式碼的使用者，會無法依靠對函式名稱的直覺來瞭解函式的本意，他們對於原作者喪失了信任感，所以必須回頭閱讀程式碼的細節。

## 在邊界上的不正確行為

不要依賴你的直覺，察看所有的邊界條件，然後替這些邊界條件撰寫測試程式。

## 無視安全規範

關閉某些編譯器的警告，也許能幫助你順利建立專案，但也付出了可能得進行無止盡除錯的風險。
關閉失敗的測試，然後告訴自己，晚些時候你會使之全數通過，就像假裝刷信用卡不用付錢般的一樣糟糕。

## 重複的程式碼

在程式裡盡可能地，找到重複的地方，並移除這些重複。

## 在錯誤抽象層次上的程式碼

## 基底類別相依於其衍生類別

## 過多的資訊

## 被遺棄的程式碼

## 垂直分隔

## 不一致性

## 雜亂的程式

## 人為的耦合

## 特色留戀

## 選擇型參數

## 模糊的意圖

## 錯置的職責

## 不適當的靜態宣告

## 使用具解釋性的變數

## 函式名稱要說到做到

## 瞭解演算法

## 讓邏輯相依變成實體相依

## 用多型取代 if/else 或 switch/case

## 遵循標準的慣例

## 用有名稱的常數取代魔術數字

## 要精確

## 結構勝於常規

## 封裝條件判斷

## 避免否定的條件判斷

## 函式應該只做一件事

## 隱藏時序耦合

## 不要隨意

## 封裝邊界條件

## 函式內容應該下降抽象層次一層

## 可調整的資料應放置於高階層次

## 避免傳遞型導覽

# 物件導向式程式語言

## 利用萬用字元來避免冗長的引入列表

## 不要繼承常數

## 常數和列舉

# 命名

## 選擇具描述性質的名稱

## 在適當的抽象層次選擇適當的命名

## 盡可能使用標準命名法

## 非模稜兩可的名稱

## 較大範圍的視野使用較長的名稱

## 避免編碼

## 命名應該描述可能的程式副作用

# 測試

## 不足夠的測試

## 使用涵蓋率工具

## 不要跳過簡單的測試

## 被忽略的測試是對模稜兩可的疑問

## 測試邊界條件

## 在程式錯誤附近進行詳盡的測試

## 失敗的模式是某種啟示

## 測試涵蓋率模式可以是一種啟示

## 測試要夠快速