代碼規範-註釋
引言-《代碼大全》
對於投機取巧的代碼註釋是錯誤的，註釋不應該幫扶難度大的代碼，就像kernighan和plauger強調的:”不要註釋糟糕的代碼—-應重寫之。”
很多人支持優質的代碼應該是自解釋的
在程序員的圈子中，有很多非常優秀的程序員都是不太願意寫註釋的，他們往往會認爲優質的代碼應該是自解釋的。在習慣性的不寫註釋時，他們會更用心地寫好變量名，函數名，代碼質量會進一步提高。
很多人支持代碼中30%+的是註釋
大部分代碼都需要維護，而維護者往往不是本人，當別人在閱讀你大篇幅代碼的時候對你的變量或函數命名理解起來可能會存在偏差，對於一些複雜的函數，一個簡單的函數名並不能很好的體現其函數功能，複雜的需求往往不易理解，而這個時候通過閱讀註釋的就能更好的理解代碼意圖。使代碼更易維護。
個人觀點
曾經的我也期望寫出自解釋風格的代碼，慢慢的當自己在維護別人代碼的時候，合理註釋相對較多的代碼，往往更易於理解和維護，而那種通篇沒有一行註釋的代碼理解起來的成本更高，而部分複雜的需求更不能簡單的通過代碼來理解。
統一規範的代碼註釋風格可以提高團隊工作效率
推薦的註釋原則
原則：
1、註釋形式統一
在整個應用程序中，使用具有一致的標點和結構的樣式來構造註釋。如果在其它項目中發現它們的註釋規範與這份文檔不同，按照這份規範寫代碼，不要試圖在既成的規範系統中引入新的規範。
2、註釋內容準確簡潔
內容要簡單、明瞭、含義準確，防止註釋的多義性，錯誤的註釋不但無益反而有害。
註釋條件：
1、基本註釋（必須加）
(a) 類（接口）的註釋
(b) 構造函數的註釋
(c) 方法的註釋
(d) 全局變量的註釋
(e) 字段/屬性的註釋
備註：簡單的代碼做簡單註釋，註釋內容不大於10個字即可，另外，持久化對象或VO對象的getter、setter方法不需加註釋。具體的註釋格式請參考下面舉例。
2、特殊必加註釋（必須加）
(a) 典型算法必須有註釋。
(b) 在代碼不明晰處必須有註釋。
(c) 在代碼修改處加上修改標識的註釋。
(d) 在循環和邏輯分支組成的代碼中加註釋。
(e) 爲他人提供的接口必須加詳細註釋。
常用註釋格式舉例
- 如果某段代碼有功能未實現，或者有待完善，必須添加“TODO”標記，“TODO”前後應留一個空格。例如
// TODO 未處理IE6-8的兼容性
function setOpacity(node, val) {
node.style.opacity = val;
}- 文檔註釋將會以預定格式出現在API文檔中。它以“/*”開頭，以“/”結束，其間的每一行均以“”開頭（均與開始符的第一個“”對齊），且註釋內容與“*”間留一個空格。例如：
/**
* comment
*/- @module。聲明模塊，用法：
/**
* 模塊說明
* @module 模塊名
*/- @method。聲明函數或類方法，用法
/**
* 方法說明
* @method 方法名
* @for 所屬類名
* @param {參數類型} 參數名 參數說明
* @return {返回值類型} 返回值說明
*/-
-
http://www.zhihu.com/question/21880307
http://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/comments/