下面是我在工作中沉澱出的一套注釋書寫規範。它沒有什麼技術含量,目的只是統一製作方式、方便後期維護,共包含四個部分:區域注釋、單行注釋、注釋層級和協助注釋。
很多人寫區域注釋會用「注釋內容開始/結束」或者「start/end」。相比之下,用「S」和「E」開頭速度更快:寫一次開始與結束的注釋,複製到其他位置,只需改動那個字母就能完成新區域的標注。
實務中經常出現一個困擾:注釋到底該寫在標籤之上還是之下?為避免糾葛,統一規定——注釋信息寫在區域標籤的開始之前與結束之後,並以「S」或「E」開頭,明確表示這是區域的起止。
示例:
<!--=S 注釋內容-->
<div>
...
</div>
<!--=E 注釋內容-->
/*=S 注釋內容*/
.class{
...
}
.class{
...
}
/*=E 注釋內容*/
單行注釋的信息,寫在需要注釋的內容區域裡面。
<div>
<!--注釋內容-->
...
</div>
.class{
/*注釋內容*/
...
}
規則記住兩條就夠:區域注釋在外、單行注釋在內;起止符號固定,讓任何人接手都能一眼看懂邊界在哪。