最近在編寫程式時, 注意到幾個關於程式註解的注意事項, 我把它記錄起來, 同時提供朋友們參考。註解內要怎麼斷行? 例如以下用來註解 interface 的程式行, 你在註解中把它斷行是無效的...
最近在編寫程式時, 注意到幾個關於程式註解的注意事項, 我把它記錄起來, 同時提供朋友們參考。
註解內要怎麼斷行? 例如以下用來註解 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<T> 就可以了!
不過, 這麼一來, 你在使用 IDataType 的程式中看起來正常了, 在 IDataType 的程式註解中, 看到的還是 List<T> 這種莫名其妙的寫法。所以我乾脆把它寫成 List(of T), 這樣兩邊都很清楚, 算是另一種變通的方法。
此外, 其實所有廣義的 White Space 字元也都會被 XML Parser 忽略。包括前面提到的換行字元、Space 字元、Tab 字元等等。那麼, 或許你的心中有疑問, 我是如何在註解的第二行開始, 做到縮行功能的? 其實我試過空白字元, 甚至 " " 標籤, 結果不是無效, 就是發生錯誤。最後, 我插入了一個中文的全形空白, 就可以了。
如果不使用全形空白, 也可以使用 ASCII 字元裡的一些字元取代, 例如 #7F (DEL, 就在 "~" 字元後面), 也有相同的效果。不過, 就實用面來說, 還是全形空白最容易而且方便使用。