/* 單行註釋 */
/*
多行註釋
詳細描述功能、用途、注意事項
*/
推薦文檔塊風格 (DocBlock),行寬 ≤ 80 字符:
/**
* 組件名稱/功能簡述
*
* 詳細說明:用途、參數、依賴、副作用等
*
* @example
* .btn { ... }
*/
避免過度修飾選擇器 (如 ul.nav 降低復用性、提高優先級),但需告知預期作用元素:
/*html*/.product-page { } /* 預期用於 html 根元素 */
/*ol*/.breadcrumb { } /* 預期用於 ol 元素 */
/*p*/.intro { } /* 預期用於 p 元素 */
/*ul*/.image-thumbs { } /* 預期用於 ul 元素 */
註釋不影響選擇器優先級,卻能傳達語義信息。
為功能模塊打標籤,便於搜索定位:
/* ^layout - 頁面佈局相關 */
.header { ... }
.footer { ... }
/* ^typography - 排版樣式 */
.heading-1 { ... }
.body-text { ... }
/* ^components - UI 組件 */
.btn { ... }
.card { ... }
搜索 ^layout 即可快速定位佈局相關代碼。
關聯分離的基礎樣式與擴展樣式:
/* base.css */
/**
* @extend .btn-primary in theme.css
*/
.btn { padding: 8px 16px; border-radius: 4px; }
/* theme.css */
/**
* @extends .btn in base.css
*/
.btn-primary { background: #007bff; color: #fff; }
建立跨文件關聯,便於維護與重構。