C# 註解完整指南：單行、多行、XML 文件註解與兩大避坑陷阱

前言：註解是專業工程師的基本素養

程式碼不只是給機器執行，更給人閱讀。良好註解習慣不浪費時間，反而提升效率，讓程式碼清晰、完整、友善。

C# 三種註解語法

1. 單行註解 //

雙斜線後至行尾內容被編譯器忽略。

// 要求使用者輸入姓名
Console.WriteLine("Please enter your name:");

2. 多行註解 /* ... */

分隔符間內容被忽略，可跨行。

/* 
本程式示範基本輸入輸出
您可以在這裡添加自己的代碼
程式在這裡結束
*/

3. XML 文件註解 ///（補充）

Visual Studio 支援 /// 自動產生標準標籤，配合 /doc 編譯選項產出 API 文件：

/// 

/// 歡迎使用者
/// 
/// 使用者名稱
public void Welcome(string name) { }

完整範例：Welcome 程式加註解

// 來源檔案: welcome.cs
/* 說明：這裡是我的第一個 C# 程式 */
using System;

class Welcome 
{
    static void Main()
    {
        Console.WriteLine("Please enter your name:");  // 要求使用者輸入姓名
        Console.ReadLine();  // 讀取使用者輸入
        Console.WriteLine("Welcome to you!");  
        /* 本行程式碼用於列印歡迎訊息：
           您可以在這裡添加自己的程式碼：
           程式在這裡結束 */
    }
}

⚠️ 兩大隱藏陷阱

陷阱 1：單行註解中的反斜線 \ 導致續行

Console.WriteLine("The result is:{0}", // \
150);

// 將該行剩餘視為註解，但 \ 是續行字元，導致下一行 150); 也被註解化 → 編譯錯誤（缺右括號）。

解法：避免單行註解尾端使用 \，或改用多行註解。

陷阱 2：多行註解不可巢狀

/* 
  程式碼片段 /* 內含註解 */ 
*/

編譯器遇第一個 /* 後忽略後續 /*，直尋下一個 */ 結束。剩餘 */ 無配對 /* → 編譯錯誤。

解法：使用預處理指令 #if false ... #endif 區塊註解含註解的代碼：

#if false
    Console.WriteLine("暫時停用"); // 內含註解也沒問題
#endif

最佳實務建議

• 公用 API 必寫 XML 文件註解
• 複雜演算法加單行註解說明意圖
• 區塊註解用 #if false 而非 /* */
• 定期清理過期註解，避免誤導