優秀的 CSS 註釋能充當「活文檔」,降低團隊認知負擔,加速維護迭代。本文介紹三種超越傳統說明的進階註釋模式。
問題:.product-page 看似根容器,實際作用於 html、body 還是 div?直接寫 html.product-page 會提升優先級、降低復用性。
解決:將類型選擇器註釋化:
/* html */.product-page { } /* 暗示作用於 html 元素 */
/* ol */.breadcrumb { } /* 暗示作用於有序列表 */
/* p */.intro { } /* 暗示作用於段落 */
瀏覽器忽略註釋,選擇器實為 .product-page,優先級為 0-1-0,完全復用。開發者閱讀時即得知預期掛載節點。
在樣式塊上方添加標準化標籤註釋:
/**
* ^navigation ^lists
*/
.nav { }
/**
* ^grids ^lists ^tables
*/
.matrix { }
開發者搜尋 ^lists 即可定位所有列表相關樣式(.nav、.matrix 等)。建議建立團隊統一標籤體系:^layout、^typography、^component-card、^utility 等。
OOCSS/BEM 架構中,基礎樣式與擴展樣式常分離於不同文件。雙向標記建立可追溯鏈接:
/* base.css */
/**
* Extend `.card` in components/card-theme.css
*/
.card { ... }
/* components/card-theme.css */
/**
* Extends `.card` in base.css
*/
.card-theme-dark { ... }
IDE 搜尋 Extend `.card` 即可跳轉關聯文件,消除「改這兒壞那兒」的恐懼。
comment-pattern 強制標籤格式。註釋是代碼的「元數據」。準修飾選擇器解決作用域文檔化、代碼標籤構建橫向索引、繼承標記串聯縱向依賴。三者結合,將 CSS 從「寫時讀懂、改時頭大」轉變為「可查、可追溯、可安心重構」的工程資產。