以下是我在實務中整理出來的一套註解撰寫慣例。技術含量不高,目的只是統一產出格式、方便後續維護,共分為區域註解、單行註解、註解層級、協助註解四個部分。若有更好的建議,歡迎提出。
常見做法會寫「註解內容開始」或「start / end」之類的標記。相比之下,用「S」與「E」開頭更快:寫一次開始與結束的註解後複製,改一下字母就能快速標完整個區域。
實務上常會遇到一個困擾:註解到底該放在標籤上方還是下方?為避免爭議,統一規則是——註解資訊寫在區域標籤開始之前與結束之後,並以 S 或 E 開頭。
<!--=S 註解內容 --> <div> ... </div> <!--=E 註解內容 -->
/*=S 註解內容 */
.class{
...
}
.class{
...
}
/*=E 註解內容 */
註解資訊直接寫在需要說明的內容區塊裡。
<div> <!-- 註解內容 --> ... </div>
.class{
/* 註解內容 */
...
}
模組製作中常出現區域套區域的情況。為了清楚表達彼此層級,這裡引入層級概念:區域註解前的等號數量即代表當前所處的層級。
<!--=S 註解內容 -->
...
<!--==S 註解內容 -->
...
<!--===S 註解內容 -->
...
<!--===E 註解內容 -->
...
<!--==E 註解內容 -->
...
<!--=E 註解內容 -->
/*=S 註解內容 */ ... /*==S 註解內容 */ ... /*===S 註解內容 */ ... /*===E 註解內容 */ ... /*==E 註解內容 */ ... /*=E 註解內容 */
當檔案由原維護者以外的人接手修改時,於既有註解上補充修改人與修改時間等識別資訊。
<!--==S 註解內容[修改人和修改時間] --> <div> ... </div> <!--==E 註解內容[修改人和修改時間] -->
/*=S 註解內容[修改人和修改時間] */
.class{
...
}
.class{
...
}
/*=E 註解內容[修改人和修改時間] */
<div> <!-- 註解內容[修改人和修改時間] --> ... </div>
.class{
/* 註解內容[修改人和修改時間] */
...
}
最後一個容易忽略的細節:撰寫註解標記的起訖時(尤其是樣式中的單行註解),註解內容與標記之間務必留一個空格,否則在 IE 下可能出現讀取不到內容的情況。