csharp-commentslisted

# C# Comments 本 Skill 規範 C# 程式碼註解的風格與用途。XML 文件註解的標籤與格式規範另見 `csharp-docs` skill，本 Skill 不重複。 ## 單行註解 - **格式**：`//` 後加一個半形空格再接內容，如 `// 計算未稅金額`。 - **位置**：置於方法或屬性**內部**的程式碼行上方，或同一行程式碼後方。不得置於方法、屬性、類別等成員宣告的正上方，該位置保留給 XML 文件註解。 - **用途**：說明「為什麼這樣做」，而非複述「程式碼在做什麼」。程式碼本身已能清楚表達的內容，不寫成註解。 ## 應寫註解的情境 以下情境即使程式碼能執行，不寫註解會讓下一個讀者卡住或踩雷，應主動補上 `//` 註解： - **隱含約束**：程式碼依賴了不看註解就無從得知的前提，例如「此方法必須在 X 之後呼叫」「順序不可調換，因為 Y 有副作用」。 - **陷阱警告**：已知的邊界條件或容易踩雷的行為，例如「此 API 在 null 時回傳空集合而非拋例外」「這裡刻意不用 async 因為呼叫端有 sync 限制」。 - **非顯而易見的業務規則**：光看程式碼只能知道「做了什麼」但無法知道「為什麼這樣做」的商業邏輯，例如稅率計算的法規依據、特定欄位截斷長度的來源。 - **Workaround 標記**：為繞過框架 bug 或第三方限制而寫的權宜寫法，標明問題來源以便日後移除。 - **正則或複雜運算式**：一眼看不出意圖的 regex pattern 或位元運算，用一行說明匹配目標或計算意圖。 ## 工作清單關鍵字 `TODO`、`UNDONE`、`HACK` 是 Visual Studio「工作清單」的預設 token，依語意分類使用，避免混用： - **TODO**：計畫要做、但尚未動工的工作，例如待補的功能或待處理的事項。 - **UNDONE**：已動工、但尚未完成的半成品工作。與 `TODO` 的差別在於是否已開始。 - **HACK**：刻意採用的權宜解法，能運作但不理想，標記為待重構的技術債。問題根治後應一併移除標記。 附註： - `UnresolvedMergeConflict` 也是工作清單的預設 token，用於標記未解決的合併衝突，非開發者手動撰寫的工作標記。 - `FIXME` 不是 Visual Studio 的預設 token（JetBrains Rider 等 IDE 則內建）。不建議另行引入：已知缺陷應進入 issue 追蹤系統，僅為小幅且明確的修正則用 `TODO` 註明即可。團隊若仍要使用 `FIXME`，須於「工具 > 選�� > 環境 > 工作清單」全員加入該 token，確保一致可見。