Clean-Code: 注釋

<b></b>

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

有幾個原因：

糟糕的代碼不是自己寫的，别人寫的代碼，還是讓别人自己去維護吧，出了問題也是别人的。

糟糕的代碼目前可以正常工作，軟體開發中有一條古老哲言：如果它能工作就不要動它，很多程式員都遵守這條準則。

既然代碼不能被修改，那麼就隻能加注釋了。

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

注釋的好處基本上大家都知道，主要是為了友善其他人更好的檢視和了解代碼，下面的一些主要是亂用注釋而導緻的壞處：

// the name

private string name;

// the version

private string version;

// the licenceName

private string licenceName;

private string info;

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

// 姓名

 private string name;

 // 版本号

 private string version;

 // 許可名稱

 private string licenceName;

 // 資訊

 private string info;

雖然注釋一樣有些多餘，不過對于英文不好的讀者來說的确友善了不少。

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

/// &lt;summary&gt;

/// IBaseManager

/// 通用接口部分

///

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

/// 修改紀錄

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

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

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

///     2007.05.19 版本：1.6 jjjco 修改完善了 Delete，Exists方法部分，<b>累了休息一下下，争取周六周日兩天内完成。</b><b></b>

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

/// &lt;author&gt;

///     &lt;name&gt;jjjco&lt;/name&gt;

///     &lt;date&gt;2007.05.23&lt;/date&gt;

/// &lt;/author&gt;

/// &lt;/summary&gt;

public interface IBaseManager

{

    xxxxxx

}

這段注釋有幾個問題：

喃喃自語，

修改記錄在有源代碼管理的情況下，完全多餘，不過鑒于最早的版本是2004.07.21,這一點，修改記錄問題也不大。

注釋中版本的不一緻，最新的版本是2007.11.01的版本1.9 .但是下面顯示的版本是1.8.版本不一緻的原因是作者忘記了，包括下面的&lt;date&gt;2007.05.23&lt;/date&gt;

msdn  解釋：

#region MyClass definition

public class MyClass

    static void Main()

    {

    }

#endregion

效果如下：

<a href="http://images.cnblogs.com/cnblogs_com/LoveJenny/201109/201109160613208926.jpg"></a>

記得以前我剛接觸#region的時候，習慣性的寫上了這樣的代碼：

<a href="http://images.cnblogs.com/cnblogs_com/LoveJenny/201109/201109160613215645.png"></a>

對于經常使用#region的同學肯定知道上面的代碼的問題。#region 後面是不需要加 “//” 的。

大師不愧是大師，另一個經典的注釋是讓你忘記不了他是如何使用#region的。

<a href="http://images.cnblogs.com/cnblogs_com/LoveJenny/201109/201109160613247960.jpg"></a>

當我看到DbLogic的時候，我徹底崩潰了。

不過在批評别人的同時，我還是要說下大師的優點：

代碼結構清晰

命名相對來說還算規範

注釋非常詳細，雖然像上面的注釋不在少數，但是不可否認的是注釋非常詳細，比如：

<a href="http://images.cnblogs.com/cnblogs_com/LoveJenny/201109/201109160613269304.jpg"></a>

本文轉自LoveJenny部落格園部落格，原文連結：http://www.cnblogs.com/LoveJenny/archive/2011/09/16/2178235.html，如需轉載請自行聯系原作者