優秀的 CSS 註釋不只是說明「做了什麼」,更要傳達「為什麼這樣做」、「如何使用」、「與誰相關」。本文介紹四大進階註釋模式:準修飾選擇器註釋、代碼標籤系統、繼承關係標記、區塊文檔註釋,助您建立可搜尋、可維護、團隊友善的樣式表文檔體系。
問題:.product-page 看起來像根容器,但實際可能掛在 body、html 或 div 上。寫 body.product-page 會提高特定度、降低複用性。
/* ✅ 準修飾註釋:註釋掉類型選擇器,保留 class 選擇器 */
/* html */.product-page { }
/* 更多範例 */
/* ol */.breadcrumb { } /* 暗示掛在 ol 上,但實際可用於任何容器 */
/* p */.intro { } /* 暗示為段落文字,但可用於 div/span */
/* ul */.image-thumbs { } /* 暗示為列表容器 */
/* 團隊約定:註釋內容 = 預期掛載元素類型,非強制要求 */
效益:零特定度成本、文檔預期結構、不限制實際使用場景、版控差異清晰。
在模組/區塊註釋中植入標準化標籤,支援編輯器「專案搜尋」快速定位相關代碼。
/* 模組區塊標註範例 */
/**
* @module Navigation
* @tags ^navigation ^header ^layout ^responsive
* @description 主導航列,包含 Logo、選單、使用者選單、行動版漢堡選單
* @dependencies variables.css, utilities.css
* @author Team Alpha
* @since 2024-01-15
*/
.nav { /* ... */ }
/**
* @module DataTable
* @tags ^tables ^grids ^data-display ^sortable ^paginated
* @description 可排序、分頁、可選取的資料表格元件
*/
.data-table { /* ... */ }
/**
* @module Button
* @tags ^buttons ^forms ^interactive ^states ^variants
* @description 基礎按鈕元件,支援 primary/secondary/outline/ghost 變體
*/
.btn { /* ... */ }
搜尋場景:開發者需修改「所有表格相關樣式」→ 搜尋 ^tables 即可定位 .data-table、.pricing-table、.comparison-table 等所有相關模組。
面向對象 CSS 中,基礎樣式與擴充樣式常分離在不同檔案/位置。繼承標記建立雙向連結:
/* ===== base/buttons.css - 基礎按鈕樣式 ===== */
/**
* @module Button Base
* @extends .btn--primary in components/buttons/primary.css
* @extends .btn--outline in components/buttons/outline.css
* @extends .btn--ghost in components/buttons/ghost.css
*/
.btn {
display: inline-flex;
align-items: center;
justify-content: center;
padding: 0.5rem 1rem;
font-weight: 500;
border-radius: var(--radius-md);
transition: var(--transition-fast);
/* 共同基礎屬性 */
}
/* ===== components/buttons/primary.css - 主要按鈕擴充 ===== */
/**
* @module Button Primary
* @extends .btn in base/buttons.css
* @description 主要行動呼籲按鈕,品牌主色背景
*/
.btn--primary {
background: var(--color-primary);
color: #fff;
border: 1px solid transparent;
}
.btn--primary:hover { background: var(--color-primary-dark); }
.btn--primary:active { background: var(--color-primary-darker); }
雙向連結效益:
@extends 清單/* ==========================================================================
MODULE: Media Object (媒體物件)
DESCRIPTION: 圖文並排通用佈局模式,支援圖片在左/右、垂直置中/頂部對齊
DEPENDENCIES: variables.css, utilities.css
AUTHOR: UI Team
LAST UPDATED: 2024-03-10
========================================================================== */
/* --- 基礎結構 --- */
.media { display: flex; align-items: flex-start; gap: var(--space-md); }
.media__figure { flex-shrink: 0; }
.media__body { flex: 1; min-width: 0; } /* min-width: 0 防止內容撐破 flex 子項 */
/* --- 修飾變體 --- */
/* @variant media--reverse 圖文順序反轉 */
.media--reverse { flex-direction: row-reverse; }
/* @variant media--center 垂直置中對齊 */
.media--center { align-items: center; }
/* @variant media--stack 小螢幕垂直堆疊 */
@media (max-width: 480px) {
.media--stack { flex-direction: column; }
.media--stack .media__figure { max-width: 100%; }
}
/* --- 狀態 --- */
.media.is-loading .media__figure::after { /* skeleton loader */ }
| 規範項目 | 建議標準 | 工具輔助 |
|---|---|---|
| 檔案頭部註釋 | 強制:模組名、描述、依賴、作者、更新日期 | Stylelint + 自訂規則 / 編輯器片段 |
| 區塊分隔註釋 | /* --- 區塊標題 --- */ 統一格式 | 編輯器代碼摺疊識別 |
| 魔法數值註釋 | 非自明數值必註釋來源 /* 1.5 = 24px / 16px */ | Code Review 檢查點 |
| Hack/暫時方案 | /* HACK: 針對 Safari 15 flex bug */ 標記並留 Issue 連結 | 定期清理 Hack 註釋 |
| TODO/FIXME | /* TODO: 支援 RTL 佈局 */ 統一格式 | IDE 任務清單整合 |
| 瀏覽器支援備註 | /* @support: Chrome 88+, Firefox 78+, Safari 14+ */ | Can I Use 整合 |
配合工具從註釋生成樣式指南:
CSS 註釋是團隊共同認知的外部化存儲。掌握準修飾選擇器(文檔結構不污染特定度)、代碼標籤(搜尋即導航)、繼承標記(雙向連結分散代碼)、標準區塊模板(降低認知負荷)四大技巧,配合自動化工具鏈,能將 CSS 從「唯有作者懂的黑盒」轉化為「團隊共享的知識資產」。