CSS/SCSS 註解規範

CSS/SCSS 註解規範

本技能用於 CSS/SCSS 檔案的註解格式指引，確保程式碼的可維護性與可讀性。

核心原則

撰寫 CSS/SCSS 時，註解應該解釋 「為什麼這樣做」（Why），而非只有 「做了什麼」（What）。

彈性捨棄雙語原則 (Flexible Bilingual Omission)

最高原則參照：依據 bilingual-standardization-rule，「彈性取捨（捨棄與保留）」 與 「技術術語錨點」 為最高原則，在 CSS/SCSS 註解中仍需嚴格遵守。

當雙語造成閱讀障礙或內容過長時，保留最清晰的一種語言即可，無需強制雙語。

本節的另一面是彈性保留雙語 (Flexible Bilingual Retention)（見本節末尾「變體」子節）—— 兩者一體兩面、本質相同：都只保留真正有雙語價值的部分，差異僅在取捨方向的微小不同。

例外：技術術語的雙語標註仍應保留（如 flex 布局 (flex layout)、偽元素 (pseudo-element)）。

判定基準 (Quick Check)： 看雙語中的英文部分——不懂英文、只理解簡單單字的人，是不是也知道？

• 知道（如 Code、Problem 這類簡單詞）→ 英文對中文讀者未提供新資訊：屬可捨棄的雙語，二擇一保留（見「無意義雙語」）
• 不知道（需具備英文程度才懂，如 flex layout、pseudo-element）→ 英文是理解與搜尋的入口：保留雙語

⚠️ 例外：「有特殊意圖的雙語」（見下方「有特殊意圖的雙語」，如 增益 / Gain）不受此基準影響—— 即使英文是簡單單字，只要中英彼此不對應、捨棄任一方即失去雙向搜尋，仍須保留。

譯名不唯一的術語 (Variant Translations)： 部分技術術語的中文譯名不唯一 （如 Cache → 快取 / 緩存 / 緩衝），中文本身即帶歧義——只留中文時，不同讀者會用不同譯名搜尋而比對不到。 這類術語兩種做法皆可，唯獨不可只保留中文譯名：

• 必要性雙語：快取 (Cache) — 譯名 + 英文錨點，兩種語言的讀者都能對上
• 僅保留英文：Cache — 以英文為唯一稱呼，從根源避免譯名分歧