我已經無數次向開發者同行宣傳為代碼作注解的重要性。但最近我發現一個奇怪的事實：許多開發者并未考慮用JavaScript或HTML編寫代碼，所以他們也很少為這類代碼作注解。用書面文件或代碼注釋徹底為JavaScript代碼作注解，不僅對您自己有幫助，對將來應用這些代碼的開發者也有指導作用。
用注釋給代碼作注解
書面文件當然不錯，但我還是喜歡用代碼編寫的文件——以防出現書面文件遺失的情況。給代碼作注解是個良好的習慣，在編寫代碼時也很容易做到。一些語言，如Java和C#提供了特定的注解功能。
JavaScript并不具備這種功能，但您可以方便地用注釋作注解。在JavaScript中有兩種進行注釋的方法：
- /*（開始注釋）與*/（結束注釋）字符組合允許您增加多行注釋，因此在注釋開始與結束指示符之間的所有代碼不被執行。
- 單行注釋放在兩個反斜杠字符（//）之間。兩個反斜杠間的所有文本都被忽略。這些注釋可以自成一行，也可放在JavaScript代碼的后面。
列表A
中的HTML樣本代碼包含了應用這兩種技巧的JavaScript代碼。這是一個簡單的HTML頁面，在頁面加載時顯示一個信息框，但其中包含許多注解。可能您寧愿開發別的技巧，但這其中的一些技巧可以專門用來為代碼作注解。畢竟，不必對優秀的代碼進行創新，但使代碼高效、方便地執行，且易于維護就很有必要。
在給代碼作注解時，哪些地方可以增加大量信息也需要一定的技巧。畢竟，并不是每行代碼都需要注解。以下是給JavaScript代碼作注解的幾點指導：
- 給所有的函數作注解，包括函數的功能，參數與返回值（如果存在）說明。我的簡單實例中包含了上述信息。我喜歡說明作者和日期，但您也可以在頁面文件中進行說明。（因為整個頁面的作者和日期可能相同），但這屬于開發者和組織的喜好。
- 對晦澀或復雜的代碼進行注解，以幫助將來的開發者了解它的作用。
- 如果代碼發生了改變，要用一行注釋進行詳細說明：由誰，為什么進行改變。這有助于調試并追蹤開發者。
這些并不是強制性的指導，不同組織的指導方針也各不相同；關鍵在于保持一致，使所有代碼都遵循同一套準則。
編寫高效代碼
注解代碼只是緩解代碼維護壓力的一個方面。您可以應用下面的另外一些技巧幫助開發者同行提高代碼的可讀性：
- 正確縮進
- 顯而易見的變量與方法名稱
- 腳本塊的括號位置保持一致
雖然TechRepublic網站的顯示細節在本文的樣本代碼中取消了行縮進，但您應該根據開發者和/或組織的喜好縮進代碼。另外，您會注意到實例中的變量與函數名稱都相當明確，開發者不必查看相應的注釋就能夠確定代碼的功能。
列表中的最后一項與包含代碼塊的大括號（）的位置有關。一些組織喜歡在代碼之前使用括號，其它組織則在第一行代碼之后應用括號。樣本代碼使用了前一種方法，但函數可以使用列表B中代碼所說明的其它技巧。
HTML
注釋
除JavaScript注釋外，您還可以用HTML格式的注釋在HTML代碼中添加注釋或注解。HTML注釋使用下面的格式：
<!-- This is an HTML comment -->
樣本代碼的頁面頂部是一行HTML注釋。注釋的位置依項目而定，但可以用它們來防止頁面的一些部分進入加載/執行過程，以幫助進行調試。
幫助其他人
編寫易讀代碼是一個每天都要進行的連續性過程。畢竟，多數開發者討厭注解，不是人人都愿意在項目完成后再倒過頭來給代碼添加注釋。您可以加入注釋，使代碼的格式保持一致，為將來進行維護或修改的開發者提供方便。
Tony Patton
擁有豐富的Java、VB、Lotus及XML方面的知識，是一個專業的應用程序開發人員。
轉自: http://www.builder.com.cn/2006/1024/326923.shtml