CloudyWing/csharp-comments

C# Comments

本 Skill 規範 C# 程式碼註解的風格與用途。XML 文件註解的標籤與格式規範另見 csharp-docs skill，本 Skill 不重複。

單行註解

• 格式：// 後加一個半形空格再接內容，如 // 計算未稅金額。
• 位置：可置於程式碼上方，或同一行程式碼後方。
• 用途：說明「為什麼這樣做」，而非複述「程式碼在做什麼」。程式碼本身已能清楚表達的內容，不寫成註解。

工作清單關鍵字

TODO、UNDONE、HACK 是 Visual Studio「工作清單」的預設 token，依語意分類使用，避免混用：

• TODO：計畫要做、但尚未動工的工作，例如待補的功能或待處理的事項。
• UNDONE：已動工、但尚未完成的半成品工作。與 TODO 的差別在於是否已開始。
• HACK：刻意採用的權宜解法，能運作但不理想，標記為待重構的技術債。問題根治後應一併移除標記。

附註：

• UnresolvedMergeConflict 也是工作清單的預設 token，用於標記未解決的合併衝突，非開發者手動撰寫的工作標記。
• FIXME 不是 Visual Studio 的預設 token（JetBrains Rider 等 IDE 則內建）。不建議另行引入：已知缺陷應進入 issue 追蹤系統，僅為小幅且明確的修正則用 TODO 註明即可。團隊若仍要使用 FIXME，須於「工具 > 選項 > 環境 > 工作清單」全員加入該 token，確保一致可見。