我們要避免那些“假註釋”。沒有附加值的註釋都是“假註釋”，比如簡單的複述代碼的功能，而這些功能都可以從類的名字，方法或者變量的名字中輕易得到的。有些工具檢查你的代碼，強制你給所有的方法，參數，返回值，變量加註釋，我認爲這是不必要的。雖說嚴格照規定做沒什麼壞處，但它要佔用你的時間，某些情況下佔用了你的“黃金時間”，而在這些有限的時間裏你本來可以產出更有價值的東西。
下面我列舉幾種註釋方式：
1. 爲什麼。
告訴人們你爲什麼要這樣做。適合於一些讓人迷惑的狀況，例如你沒有用常用的招數，用了一些“歪招”。
2. 怎麼做。
告訴人們你是怎麼實現目標的。適合於一些需求清晰的情況。比如你是怎麼去實現“分頁”功能的。
3. 舉例說明。
這個我覺得最直觀，對閱讀代碼的人最友好。適合於輸入輸出數據簡單，關係明瞭的情況，比如：
/**
* Convert zone name to internal format.
* samples:
* 12.34.56.78 > 56.34.12.in-addr.arpa%
* 12.34.56.78. > 56.34.12.in-addr.arpa%
* 12.34.56 > 56.34.12.in-addr.arpa%
* 12.34.56. > 56.34.12.in-addr.arpa%
* sina.com > %sina.com%
* sina.*.cn > sina.%.cn%
* sina.* > sina.%
* 56.*.12.in-addr.arpa > 56.%.12.in-addr.arpa%
*
*/
4. 參考資料。
把參考資料的鏈接，或者位置寫出來，讓閱讀代碼的人可以去進一步瞭解。比如：
/**
* We have some violations between old system data and new system data, like
* abbreviation value and full value, so we need to do some convert action. Please
* refer to xxx.
*/
5. 維護建議。
這個很有價值，也會讓後面維護的人很感激。
/**
* Here is the only place to change the city codes and rdc codes.
* The format of each line is
* [City Name]|[City Value]|[RDC Name]|[RDC Value]
*
* Please put the same rdc value in one bunch,
* e.g.
* 'Lafayette|lf|Baton Rouge|br',
* 'Baton Rouge|br|Baton Rouge|br',
*/
6. 開發故事。
講一下你開發的過程，決策的過程，以及任何有價值的信息。比如：
/**
* The old implementation have so many repeated code and redundant pages, we have removed
* all those repeated things and deleted more than 20 pages. It's a big improvement even there
* are some ugly javascript code here, we should use JSON to encapsulate the data and move all
* javascript to menus.jsp page, this is next step.
*/
怎麼把文檔和註釋有機的結合在一起，優勢互補，這是一個可以深入討論的命題。比如可以參照REST的理念，把文檔，代碼和註釋資源化，用一個工具把這些東西自動編譯整理爲對人友好的開發文檔，項目文檔等。
原文：http://blog.csdn.net/kevinkevin/article/details/6570625