優秀的 CSS 註解能:降低認知負荷、加速新人上手、支援自動化文檔生成、輔助程式碼導航。系統化的註解策略是專業代碼庫的標誌。
/* 關閉連結圖片預設邊框 */
img { border: 0; }
/* ===== 按鈕變體:主要/次要/危險 ===== */
.btn--primary { background: var(--color-primary); }
.btn--secondary { background: var(--color-secondary); }
.btn--danger { background: var(--color-danger); }
/*!
* Project Name v2.3.1
* Updated: 2024-01-15 14:30
* Author: Frontend Team
* License: MIT
*/
建議:使用 /*! ... */ 確保壓縮時保留版權資訊。
/* ===================================
1. RESET & NORMALIZE
=================================== */
@import "reset.css";
/* ===================================
2. DESIGN TOKENS (CSS Variables)
=================================== */
@import "variables.css";
/* ===================================
3. LAYOUT
=================================== */
/* =HEADER --------------------------- */
.header { ... }
/* =MAIN ----------------------------- */
.main { ... }
/* =FOOTER --------------------------- */
.footer { ... }
/* =HEADER =========================== */
.header { ... }
/* =HERO ============================= */
.hero { ... }
/* 在 VS Code 大綱視圖 / 命令面板輸入 @ 即可快速跳轉 */
| 標記 | 含義 | 範例 |
|---|---|---|
@todo | 待辦事項 | /* @todo: 支援深色模式 */ |
@fixme | 已知問題需修復 | /* @fixme: Safari flex gap bug */ |
@hack | 瀏覽器 Hack 臨時方案 | /* @hack: IE11 min-width bug */ |
@deprecated | 即將移除 | /* @deprecated v3.0 改用 .btn-primary */ |
@see | 參考連結 | /* @see https://css-tricks.com/... */ |
/* ... */,單行可用 //(需預處理器支援)