---
# System prepended metadata

title: Clean Code - Ch04 註解
tags: [Clean Code, Book]

---

# Clean Code - Ch04 註解

不要替糟糕的代碼寫註解，放對位置及敘述正確註解可以帶來幫助，放錯位置及敘述錯誤的註解也可以帶來問題，不正確的註解比沒有註解還糟糕，只有代碼是正確的，因此應該努力減少註解的數量

## 1. 適當的註解是用來彌補代碼表達意圖的失敗
好的名稱可以取代註解，下一個使用者只要看變數或function的名稱就可以一目了然的理解用途，而不需要特別在看註解輔助了解，但有時候還是會有情況無法避免需要寫註解的情況
``` csharp
// fix on 2019/01/02
```

## 2. 註解可能會隨著代碼的演化而失去功能
因為我們每次改動代碼都是看懂了之後再改，裡面的每次修改都是順便維護自己的代碼一次，但你不一定會改動相對應的註解，使得註解過了一陣子候可能就沒辦法提供正確的輔助功能

## 3. 有意義的註解
**1. 法律型的註解**
``` csharp
// copyright
```
**2. 資訊型註解**
``` csharp
// return YYYY/MM/DD HH:mm:ss
public string TimeFormat(DateTime date) {
    // format it
}
```
**3.  Todo**
``` csharp
// Todo：add something
```
**4. Use for doc**
但是這種類型的註解也不該每個functtion都寫，因為久了也是會容易沒有更新
``` csharp
/// <summary>  
/// Format DateTime to custom string.
/// </summary> 
/// <param name="date">Oringin date time</param>   
/// <returns>Custom DateTime format</returns>  
public string TimeFormat(DateTime date) {
    // format it
}
```

## 4. 不好的註解
**1. 喃喃自語**
沒有說出重要的原因，變成只是在murmur而已
``` csharp
public bool Process() 
{
    try
    {
        this.step1();
        this.step2();
        this.step3();
        
        return true;
    }
    catch (Exception ex)
    {
        // Don't mind about why this exception does not do any thing.
    }
    return false;
}
```
**2. 多餘的註解**
不看註解也可以了解代碼在做什麼，甚至看註解反而更花時間
``` csharp
public bool Process() 
{
    try
    {
        // 1. run step1 to do something.
        this.step1();
        // 2. run step2 to do something.
        this.step2();
        // 3. run step3 to do something.
        this.step3();
        
        return true;
    }
    catch (Exception ex)
    {
    }
    return false;
}
```
**3. 日誌型註解**
在以前沒有版控系統的年代，常常會把修改紀錄註解在檔案最上面，但現在應該要改用版控來取代掉這件事，不該再出現這種註解，因為這個會造成檔案變得更亂
``` csharp
// 2019/01/01： do something1
// 2019/01/02： do something2
// 2019/01/03： do something3
// 2019/01/04： do something4
```
**4. 標記行註解**
如果寫太多的話容易變成只是一種背景而已，反而不會注意到他，而且還會讓代碼看起來變的雜亂
``` csharp
public void Process() {

/////Start Line///

//Do Something....

/////End Line///
}

```
**5. 被註解起來的代碼**
容易讓人擔心這段代碼是不是還有用處而不能隨意刪除，變成沒人敢動，之後要重構的人看到也要再花時間去理解這段是不是真的廢棄了

###### tags: `Clean Code` `Book`