註解

什麼是註解

註解是寫在程式碼內、用來幫助開發人員看懂邏輯的說明文字，不屬於可執行程式碼的一部分，編譯器在編譯時會直接忽略所有註解內容，不會進行轉譯。

除了輔助閱讀，我們也能透過標註程式碼來除錯找問題。當程式出現異常卻找不到錯誤位置時，可以把懷疑有問題的區段加上註解；被標註的程式會被編譯器略過，藉此逐步隔離錯誤區塊、排查問題根源。

註解的概念就像上學時我們寫在課本上的眉批筆記，額外補充的說明能幫助我們更容易理解內文含義。

註解分類

註解類型	開頭標記	結尾標記	核心規則
單行註解 Single-line	//	該行結尾	僅作用於當前完整一行，同一行//後方所有文字都會被捨去
區塊註解（分段註解）Delimited	/*	*/	可跨多行、也能嵌入程式片段中，不支援巢狀包覆
文件註解 Documentation	///	該行結尾	內嵌XML標籤，專門用來自動產生專案API參考文件

1. 單行註解 //

1. 從//開始，直到當前行最後的所有內容都會被編譯器忽略；
2. 可以寫在整行開頭，或是放在程式敘述後面；
3. 沒有巢狀限制，不會和/* */區塊註解產生語法衝突。

// 行首單行註解：宣告數值變數
int num = 10; // 程式後單行註解：存放數字10
// int temp = 99; // 整行程式標註停用，適合除錯測試；暫時讓程式不執行但不刪除，後續要恢復直接移除註解即可Code language: JavaScript (javascript)

2. 區塊註解 /* */

1. 必須成對使用開頭與結束標記，兩標記中間全部文字都會被忽略；以/*開頭、*/作結尾
2. 支援跨越多行，也能用來標註同一行內局部程式片段；
3. 禁止巢狀區塊註解，編譯器讀到第一個*/就直接結束該段註解，剩餘孤立的*/會觸發語法錯誤。

基礎範例

/*
多行區塊註解示範
編譯器會跳過這裡全部內容
可撰寫任意行說明文字
*/
string str = "測試文字";Code language: JavaScript (javascript)

/*
Multi-line delimited comment example
All content here is ignored by the compiler
Text can span any number of lines
wellcome to foxdevelop.com
*/
string greet = "wellcome to foxdevelop.com";
Console.WriteLine(greet);Code language: JavaScript (javascript)

巢狀書寫會發生編譯錯誤

在區塊註解內又放入另一組區塊標記，會造成最後一個結束符號找不到對應的開頭標記，因此程式編譯失敗。

行內局部標註

只遮蔽單行內一小段程式，下方範例中變數a就被完整註解排除。

int /*a,*/ b; 
// 等同 int b; 中間的a, 被註解遮蔽不會執行Code language: JavaScript (javascript)

錯誤巢狀區塊寫法

執行報錯

/* 外層區塊開頭
    /* 內層巢狀標記（僅視為一般文字，無作用） */
// 上方第一個*/直接關閉外層註解，下方剩餘*/沒有對應開頭，觸發語法錯誤
*/Code language: JavaScript (javascript)

單行註解//內寫/*不會啟動區塊註解

等於把這組區塊標記本身也變成註解文字，不會生效。

// 這是單行註解 /* 這裡的/*只是普通文字，不會開啟區塊註解功能
int x = 5;
/* 開啟區塊註解範圍 */ // 區塊到此結束，後面//正常發揮作用Code language: JavaScript (javascript)

3. 文件註解 ///

1. 外觀和單行註解相似，使用三個連續斜線///標示；
2. 內建XML標籤格式，開發工具可讀取並自動產生API參考說明文件；
3. 習慣寫在類別、方法、屬性上方，用來說明對外開放的介面功能。

/// <summary>
/// 程式進入點主類別
/// </summary>
class Program
{
    /// <summary>
    /// 程式執行入口方法
    /// </summary>
    /// <param name="args">命令列參數陣列</param>
    static void Main(string[] args)
    {

    }
}Code language: JavaScript (javascript)

重點總結

1. 區塊註解/* */不支援巢狀包覆，遇到第一個*/就直接終止該段註解；
2. //單行註解僅限當前一行，無法跨越多行；內部出現的/*只當作一般文字，不會開啟區塊模式；
3. C# 的單行、區塊註解語法規則和 C/C++ 完全相同；
4. 撰寫註解原則：不要重複敘述程式表面動作，重點解釋程式業務用途、設計邏輯，方便後續維護；只複製變數名稱的註解毫無實用價值。
5. 簡短單行說明、暫時停用單行程式 → 使用 //
6. 批量遮蔽多行程式、單行內局部片段停用 → 使用 /* */
7. 類別/方法介面說明、自動產生專案文件 → 使用 ///

※ 如何自動產生說明文件

以下內容僅供參考，文件註解大多使用在大型商業專案；初學階段只需知道有此功能即可，不用深入操作。

Visual Studio 設定步驟

1. 專案按右鍵 → 屬性 → 建置(Build)頁籤；
2. 勾選選項：產生 XML 文件 (Generate XML documentation file)；
3. 預設輸出路徑：bin\Debug\專案名稱.xml，可自訂儲存位置；
4. 切換為全部組態(All Configurations)勾選，Debug、Release模式都會輸出XML；
5. 重新建置專案，專案資料夾內就會產生完整XML註解檔。

.NET CLI 命令列設定（未安裝VS時）

打開專案的 .csproj 檔案，加入下方標籤區段：

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
Code language: HTML, XML (xml)

執行建置指令：

dotnet build

作用說明

這份XML檔會儲存所有<summary>、<param>、<returns>等文件標籤內容，是自動產生說明文件的資料來源；同時VS會讀取該檔，在IntelliSense滑鼠提示視窗顯示註解內容。

其他產文件工具

微軟官方 DocFX（微軟推薦、操作簡單，輸出靜態HTML網站式文件）

Sandcastle（微軟老牌工具，可匯出離線CHM輔助說明檔）

第三方輕量工具（例如 Doxygen）

以上三種註解語法完整介紹完畢