XML Documentation常見陷阱一則

2014-08-18 10:04 PM

小測驗，以下程式碼有什麼問題？（請忽略程式實用價值）

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

namespace ClassLibrary

    /// <summary>

    /// 測試類別

    /// </summary>

    public class Boo

        /// <summary>

        /// 數字

        /// </summary>

        public int Value { get; set; }

        /// <summary>

        /// 若 Value > 100，傳回true

        /// </summary>

        public bool IsBig

get

                return Value > 100;

        /// <summary>

        /// 若 Value < 100，傳回true

        /// </summary>

        public bool IsSmall

get

                return Value < 100;

        /// <summary>

        /// First Name & Last Name

        /// </summary>

        public string FullName { get; set; }

答案藏在XML Documentation裡：註解用到特殊字元＜、＞及&卻未額外處理，轉成XML程式文件會爆炸：

「>」未與「＜」成對時不易誤判，尚能正常顯示；但「<」及「&」會跟後方內容一起被解讀成HTML標籤或特殊符號，就會出現上圖中的<!—Badly formed XML comment ignored form member "…" –>。在專案使用DocsByReflection讀取XML文件，也跟著爆炸：（原本預期出現<member />的地方出現<!—... –>導致節點讀取失敗）

An unhandled exception of type 'System.InvalidCastException' occurred in DocsByReflection.dll
Additional information: Unable to cast object of type 'System.Xml.XmlComment' to type 'System.Xml.XmlElement'.

註解問題被視為警告不影響編譯，卻也常被忽略，直到轉為Help文件或用於整合時才發現。在要求「0 Warning」的專案裡註解問題很難被無視（如下），但你知道的，理想與現實總是有差距的… （掩面）