良好的程式碼註解是專案可維護性的關鍵，但濫用或錯誤的註解反而會成為閱讀障礙。本文整理出五大核心原則，助你撰寫精準、高效的註解。
註解的首要目的是釐清程式邏輯。錯誤、過時或模糊的註解不僅無益，更會誤導維護者，造成「有害無利」的後果。務必確保註解內容與程式碼實際行為完全一致。
程式碼本身應盡可能自述性強。註解僅作為對複雜邏輯、非直觀決策的補充提示，切勿讓大量註解淹沒核心程式碼，導致主次顛倒。
對於變數命名清晰、邏輯直觀的程式碼片段（如 i++、簡單賦值），添加註解屬於畫蛇添足。保持程式碼整潔，讓「代碼即文檔」成為常態。
團隊協作中，個人習慣的縮寫極易產生誤解。註解應使用通用術語、完整單詞，確保不同背景的開發者都能無障礙理解。
優秀的註解解釋設計意圖、業務規則或演算法選型理由（Why），而非逐行翻譯語法（How）。編譯器負責執行細節，人類需要理解決策背景。
遵循這五大原則，能讓註解真正成為提升團隊協作效率的催化劑，而非技術債務的溫床。養成良好註解習慣，從今天的每一次提交開始。
