萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網頁製作 >> Div CSS 教學

CSS 註釋規範與進階用法:DocBlock 風格、準修飾選擇器、代碼標籤、繼承標記

基礎註釋語法

/* 單行註釋 */
/* 
  多行註釋
  可跨行
*/

⚠️ CSS 無單行 // 註釋(Less/Sass/Stylus 支援,但原生 CSS 不支援)。

推薦:DocBlock 風格區塊註釋(行寬 ≤ 80 字元)

/**
 * 元件名稱:主要導覽列
 * 描述:固定頂部、響應式摺疊、支援多層下拉
 * 作者:Team UI
 * 版本:2.1.0
 * 依賴:variables.css, mixins.css
 *
 * 修改記錄:
 * 2024-01-15 新增行動版漢堡選單動畫
 * 2024-03-22 修正 IE11 flex bug
 */

進階用法一:準修飾選擇器註釋

避免過度修飾選擇器(如 ul.nav → .nav),但保留語意提示:

/* nav */ .primary-nav { }      /* 預期掛在 <nav> */
  /* ol */ .breadcrumb { }      /* 預期掛在 <ol> */
  /* p */ .lead-text { }        /* 預期掛在 <p> */
  /* ul */ .image-gallery { }   /* 預期掛在 <ul> */

優點:不增加優先級、不影響複用性、文檔化預期 HTML 結構。

進階用法二:代碼區段標籤(搜尋導航)

/* ==== RESET & BASE ==== */
/* >>> TYPOGRAPHY <<< */
/* --- COMPONENTS: BUTTON --- */
/* ### LAYOUT: GRID ### */
/* @@ THEME: DARK MODE @@ */

編輯器搜尋 >>>、---、###、@@ 可快速跳轉區段。

進階用法三:繼承/擴展關係標記(OOCSS/ITCSS 架構)

/* base.css */
/**
 * @extend .card in components/card.css
 */
.card-base {
  border-radius: 8px;
  box-shadow: 0 2px 8px rgba(0,0,0,.1);
}

/* components/card.css */
/**
 * @extends .card-base from base.css
 */
.card {
  padding: 1.5rem;
  background: #fff;
}

建立跨檔案的語意連結,便於重構與追蹤依賴。

註釋最佳實踐清單

  • 每個檔案頂部:檔案用途、依賴、版本、作者
  • 每個主要區塊:功能描述、HTML 結構參考、響應式斷點
  • 複雜計算/魔法數字:來源說明(如 /* 16px base * 1.5 = 24px */)
  • Hack/Workaround:Bug 連結、影響瀏覽器、預計移除版本
  • TODO/FIXME/NOTE:統一前綴,配合 IDE 任務列表

自動化工具整合

  • Stylelint:強制註釋規範(selector-class-pattern、comment-pattern)
  • PostCSS:移除生產環境註釋(postcss-discard-comments)
  • Style Dictionary / Theo:從設計令牌自動生成帶註釋的 CSS 變數檔

延伸閱讀

建立註釋規範後,建議學習 CSS RGB 色彩模型與應用技巧,精準掌控視覺設計語言。

copyright © 萬盛學電腦網 all rights reserved