Clean-Code: 註釋

別給糟糕的代碼加註釋-----------------重新寫吧

這是書中的關於註釋一章的第一句話，怎麼說呢，這句話個人感覺很對，但是實際上卻很少這麼做，

有幾個原因：

糟糕的代碼不是自己寫的，別人寫的代碼，還是讓別人自己去維護吧，出了問題也是別人的。
糟糕的代碼目前可以正常工作，軟件開發中有一條古老哲言：如果它能工作就不要動它，很多程序員都遵守這條準則。
既然代碼不能被修改，那麼就只能加註釋了。

上面的幾個原因純粹是自己的想法，希望你不要和我一樣。

註釋的好處基本上大家都知道，主要是爲了方便其他人更好的查看和理解代碼，下面的一些主要是亂用註釋而導致的壞處：

可怕的註釋，廢話註釋：

// the name

private string name;

// the version

private string version;

// the licenceName

private string licenceName;

// the version

private string info;

上面的代碼註釋的確多餘了，並且還有剪切-粘貼錯誤，我想這可能是因爲作者是外國人，所以對外國人來說英語是母語。但是中國的程序員大部分都用中文註釋。所以上面的代碼可能是這樣：

// 姓名

private string name;

// 版本號

private string version;

// 許可名稱

private string licenceName;

// 信息

private string info;

雖然註釋一樣有些多餘，不過對於英文不好的讀者來說的確方便了不少。

下面的示例是我從某位大師的系統中抽取出來的

/// <summary>

/// IBaseManager

/// 通用接口部分

///

/// 總覺得自己寫的程序不上檔次，這些新技術也玩玩，也許做出來的東西更專業了。

/// 修改紀錄

///

/// 2007.11.01 版本：1.9 jjjco 改進 BUOperatorInfo 去掉這個變量，可以提高性能，提高速度，基類的又一次飛躍。

/// 2007.05.23 版本：1.8 jjjco 修改完善了對象事件觸發器，完善了GetDT, ref 方法部分。

/// 2007.05.20 版本：1.7 jjjco 修改完善了對象事件觸發器，完善了GetDT方法部分。

/// 2007.05.19 版本：1.6 jjjco 修改完善了 Delete，Exists方法部分，累了休息一下下，爭取週六週日兩天內完成。

/// 2007.05.18 版本：1.5 jjjco 規範了一些接口的標準方法，進行了補充。

/// 2007.05.17 版本：1.4 jjjco 重新調整主鍵的規範化，整體上又上升了一個層次了。

/// 2006.02.05 版本：1.3 jjjco 重新調整主鍵的規範化。

/// 2005.08.19 版本：1.2 jjjco 參數進行改進

/// 2004.07.23 版本：1.1 jjjco 增加了接口ClearProperty、GetFromDS 的定義。

/// 2004.07.21 版本：1.0 jjjco 提煉了最基礎的方法部分、覺得這些是很有必要的方法。

///

/// 版本：1.8

///

/// <author>

/// <name>jjjco</name>

/// <date>2007.05.23</date>

/// </author>

/// </summary>

public interface IBaseManager

{

xxxxxx

}

這段註釋有幾個問題：

喃喃自語，
修改記錄在有源代碼管理的情況下，完全多餘，不過鑑於最早的版本是2004.07.21,這一點，修改記錄問題也不大。
註釋中版本的不一致，最新的版本是2007.11.01的版本1.9 .但是下面顯示的版本是1.8.版本不一致的原因是作者忘記了，包括下面的<date>2007.05.23</date>