# Clean Code - Ch04 註解

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

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

// fix on 2019/01/02

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

## 3. 有意義的註解
**1. 法律型的註解**

// copyright

**2. 資訊型註解**

// return YYYY/MM/DD HH:mm:ss
public string TimeFormat(DateTime date) {
    // format it
}

**3. Todo**

// Todo：add something

**4. Use for doc**
但是這種類型的註解也不該每個functtion都寫，因為久了也是會容易沒有更新

/// <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而已

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. 多餘的註解**
不看註解也可以了解代碼在做什麼，甚至看註解反而更花時間

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. 日誌型註解**
在以前沒有版控系統的年代，常常會把修改紀錄註解在檔案最上面，但現在應該要改用版控來取代掉這件事，不該再出現這種註解，因為這個會造成檔案變得更亂

// 2019/01/01： do something1
// 2019/01/02： do something2
// 2019/01/03： do something3
// 2019/01/04： do something4

**4. 標記行註解**
如果寫太多的話容易變成只是一種背景而已，反而不會注意到他，而且還會讓代碼看起來變的雜亂

public void Process() {

/////Start Line///

//Do Something....

/////End Line///
}

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

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