CSS 無原生模組化機制(@import 不算),註解成為唯一的「地圖」。優質註解能:
放在檔案最開頭,建立全局導航:
/*------------------------------------
1. Reset / Normalize
2. Variables / Custom Properties
3. Base (Typography, Links)
4. Layout (Grid, Container, Header, Footer)
5. Components (Button, Card, Form, Modal)
6. Utilities / Helpers
7. Page-specific Overrides
8. Themes / Dark Mode
----------------------------------- */
每個大區段前加上統一格式標題:
/*** 4. Layout ***/
#header { ... }
#footer { ... }
/*** 5. Components ***/
.btn { ... }
.card { ... }
#content h1 { color: #F00; } /* 品牌色強制覆蓋,勿輕易修改 */
#content .recent {
overflow: hidden;
/* 清除浮動副作用,見 issue #1234 */
}
| 標記 | 用途 | 範例 |
|---|---|---|
TODO: | 待辦優化/重構 | /* TODO: 移至元件庫 */ |
FIXME: | 已知 Bug 暫時修補 | /* FIXME: IE11 flex bug */ |
HACK: | 非標準手段 | /* HACK: 修正 Safari flex shrink */ |
REVIEW: | 需代碼審查確認 | /* REVIEW: z-index 9999 衝突風險 */ |
stylelint 強制區段標題格式。/* 設定紅色 */ color: red;(程式碼自述)/* 品牌主色,定義於 variables.css */ color: var(--brand-primary);(提供上下文)把註解當作給未來的自己(或隊友)寫的文件,投資極小、回報極大。更多團隊協作規範,請參考本站前端工程化專題。