註解不會影響頁面顯示,卻會深深影響維護效率。尤其當多人共同開發時,清楚的 CSS 註解能讓其他人快速理解每個區塊的用途,也能減少誤刪或誤改。
區域註解適合標示一大段樣式的起點與終點。為了避免混淆註解究竟屬於上方還是下方元素,建議將註解寫在區域開始之前與結束之後,並使用 S 與 E 表示 Start 與 End。
/*=S 註解內容 */
.class {
...
}
/*=E 註解內容 */
單行註解適合放在需要說明的內容附近,例如某個特殊 hack、瀏覽器修正或臨時調整。
.class {
/* 註解內容 */
...
}
在大型模組中,區域裡可能還有區域。此時可用等號數量表示層級,讓結構更清楚。
/*=S 一級區域 */ /*==S 二級區域 */ /*===S 三級區域 */ /*===E 三級區域 */ /*==E 二級區域 */ /*=E 一級區域 */
當非原作者維護時,可加入修改人與修改時間等資訊,方便追蹤變更來源。
/*=S 註解內容[修改人與修改時間] */ /*=E 註解內容[修改人與修改時間] */
另外要特別注意,註解標記與內容之間最好保留空格,避免部分舊版瀏覽器解析異常。良好的註解習慣,能讓 CSS 不只是給機器讀,也能給人讀。