優秀的 CSS 註解能成為活文件,輔助代碼審查、新人上手、架構追溯。本文介紹 DocBlock 風格、準修飾選擇器、代碼標籤、繼承標記四大進階技巧。
/* 單行註解 */
/*
多行註解
可跨多行
*/
行寬 ≤ 80 字元,結構化描述模組用途、參數、範例:
/**
* 模組名稱:主要按鈕 .btn-primary
* 說明:主要行動呼籲按鈕,支援 disabled、loading 狀態
* 依賴:base.css (reset), variables.css (color tokens)
* 範例:
*
*
* 版本:1.2.0
* 作者:Frontend Team
*/
優點:IDE 可解析生成文件,新成員快速理解模組契約。
避免過度限定選擇器(如 ul.nav → .nav),但需告知預期掛載元素:
/* html */ .page-home { } /* 預期掛載於 html/body */
ul.breadcrumb { } /* 預期 ul */
p.intro { } /* 預期 p */
ul.image-thumbs { } /* 預期 ul */
將類型選擇器註解化,保留語意不增加權重,兼顧複用性與可讀性。
在模組區塊頂部加入可搜尋標籤:
/* ^buttons:primary */
/* ^forms:login */
/* ^layout:header */
開發者搜尋 ^buttons 即可定位所有按鈕相關樣式,極大提升大型代碼庫導航效率。
面向對象 CSS 中,基礎類別與擴充類別常分離於不同檔案。雙向標記建立關聯:
/* base.css */
/**
* @extend .btn-primary in theme.css
*/
.btn { /* 基礎按鈕樣式 */ }
/* theme.css */
/**
* @extends .btn in base.css
*/
.btn-primary { /* 擴充主要按鈕 */ }
跨檔追蹤不再靠記憶,搜尋 @extend/@extends 即可跳轉。
stylelint-comment-require 強制關鍵模組必註解。將註解視為代碼的一等公民,投入適度精力,回報是長期可維護的架構清晰度。