寫代碼的人大概都有過這樣的經歷:三個月前自己寫的一段腳本,如今再看卻要反覆推敲才明白用意。注釋就是為了對抗這種遺忘而存在的。
最直接的價值在於「寫給未來的自己」。為一段邏輯標上用途說明,隔了半年回頭看,思路能立刻接上,不必從頭推演一遍。
往團隊協作的角度想,價值就更明顯了。同一份代碼往往有多人接力維護,清晰的注釋能讓同事快速理解每個模組的職責邊界,溝通成本自然下降。這也是為什麼規範化的項目通常會要求注釋覆蓋公共介面與非顯見的業務判斷。
HTML 的注釋寫法只有一種:
<!--注釋文字 -->
被包裹的內容不會呈現在頁面上,也不會被瀏覽器解析渲染,但會原封不動地留在原始碼裡。這一點要特別留意:注釋不是加密,敏感資訊絕不能寫在裡面。
實務中最常見的用法,是用成對的起訖標記把一個功能區塊圈起來,方便日後整段搬移或刪除:
<!DOCTYPE HTML> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <title>HTML的代碼注釋</title> </head> <body> <!--在線咨詢 begin--> <div> <p>一站式報名咨詢、助學答疑服務,無論是報名、選課、學習、做作業、考試、寫論文,畢業,這裡都有專業老師為你答疑解惑!<a href="https://hovertree.com/">向報名顧問咨詢</a></p> </div> <!--在線咨詢 end--> </body> </html>
這裡的 begin 與 end 配對,一眼就能看出區塊的起點和終點。當這個「在線咨詢」模組需要下線時,只要把兩段標記之間的內容整塊移除即可,不必逐行辨認哪裡是頭哪裡是尾。
注釋要寫「為什麼」,而不是複述「做了什麼」。程式碼本身已經說明了做法,值得記錄的是背後的取捨,例如為什麼選了這個方案、繞過了哪個瀏覽器的缺陷。
此外,注釋也應該保持整潔。註釋掉的舊代碼累積太多,反而會讓文件變得難以閱讀,不如交給版本控制去保存歷史。