.Net 程式內註解的幾個小細節

最近在編寫程式時, 注意到幾個關於程式註解的注意事項, 我把它記錄起來, 同時提供朋友們參考。

註解內要怎麼斷行? 例如以下用來註解 interface 的程式行, 你在註解中把它斷行是無效的:

/// <summary>
/// The following methods must be implemented:
/// 　bool Delete(int Id);
/// 　bool Insert();
/// 　bool Update();
/// 　string ToString();
/// 　int Compare(Object x, Object y);
/// 　int CompareTo(object obj);
/// 　new bool Equals(object obj1, object obj2);
/// 　int GetHashCode(object obj);
/// 　internal static extern int InternalGetHashCode(object obj);
///     
/// Also implement these (not defined in this interface):
/// 　static void Refetch();
/// 　static int Count();
/// 　static List(of T) GetList(bool Refetch=false);
/// 　static T GetById(int Id);
/// </summary>
/// <typeparam name="T">The type you are using</typeparam>
public interface IDataType<T> : IComparable, IComparer<object>, IEqualityComparer<object>
{
    bool Delete();
    int Insert();
    bool Update();
    string ToString();
    ...

以這種方式註解的 interface, 在 Visual Studio 的提示中, 會以如下的方式呈現:

換句話說, 不管你在註解中如何斷行, VS 在呈現時, 仍然會把所有文字全部擠在一起。如果你看到斷行, 那也是因為上一行太長, 才把多餘文字擠到下一行的關係。自行加入 \r\n 或者 <br /> 標簽, 都是無效的。

想讓你的註解正確地斷行, 方法很簡單, 就是多打幾個字, 從第二行開始, 在前後包上 <Para> 標簽即可。所以, 把以上的程式改寫如下即可:

/// <summary>
/// The following methods must be implemented:
/// <para>　bool Delete(int Id);</para>
/// <para>　bool Insert();</para>
/// <para>　bool Update();</para>
/// <para>　string ToString();</para>
/// <para>　int Compare(Object x, Object y);</para>
/// <para>　int CompareTo(object obj);</para>
/// <para>　new bool Equals(object obj1, object obj2);</para>
/// <para>　int GetHashCode(object obj);</para>
/// <para>　internal static extern int InternalGetHashCode(object obj);</para>
///     
/// <para>Also implement these (not defined in this interface):</para>
/// <para>　static void Refetch();</para>
/// <para>　static int Count();</para>
/// <para>　static List(of T) GetList(bool Refetch=false);</para>
/// <para>　static T GetById(int Id);</para>
/// </summary>
/// <typeparam name="T">The type you are using</typeparam>
public interface IDataType<T> : IComparable, IComparer<object>, IEqualityComparer<object>
{
    bool Delete();
    int Insert();
    bool Update();
    string ToString();
    ...

這麼一來, VS 在顯示這段註解的時候, 就會以另一種方式呈現:

此外, 或許你有注意到, 我在註解中把 List<T> GetList 這個方法改寫成了 List(of T)。

為什麼要這麼寫? 這是因為如果你在註解中加上任何方括號 (包括 <T>), VS 都會把它當作是 XML 標簽, 然後在解析時發生例外錯誤。坦白說, 這個帳也許不能算在 VS 頭上, 因為 VS 把註解以 XML 文件存放, 而其內容是以 XML 節點內容值的格式記錄的, 等同於 PCDATA 格式 (如果你想了解 PCDATA 和 CDATA 的差異, 請參考我以前寫的「[入門][XML] XML入門系列 (1) : XML 初論」一文); 所以, 有某些字元無法被 Parser 接受 (像是 "<", ">", "&" 等等)。

解決的方法和 XML 文件的解決方法一樣, 就是在註解中把 <T> 寫成 List&lt;T&gt; 就可以了!

不過, 這麼一來, 你在使用 IDataType 的程式中看起來正常了, 在 IDataType 的程式註解中, 看到的還是 List&lt;T&gt; 這種莫名其妙的寫法。所以我乾脆把它寫成 List(of T), 這樣兩邊都很清楚, 算是另一種變通的方法。

此外, 其實所有廣義的 White Space 字元也都會被 XML Parser 忽略。包括前面提到的換行字元、Space 字元、Tab 字元等等。那麼, 或許你的心中有疑問, 我是如何在註解的第二行開始, 做到縮行功能的? 其實我試過空白字元, 甚至 "&nbsp;" 標籤, 結果不是無效, 就是發生錯誤。最後, 我插入了一個中文的全形空白, 就可以了。

如果不使用全形空白, 也可以使用 ASCII 字元裡的一些字元取代, 例如 #7F (DEL, 就在 "~" 字元後面), 也有相同的效果。不過, 就實用面來說, 還是全形空白最容易而且方便使用。

歡迎加入 .NET 2Share on FaceBook 歡迎加入 .NET 2Share on Google+