我過去以為寫詳細的註解是正面的行為，應該盡可能這麼做。這幾年下來在實際工作中發現事情不是這樣，首先要承認有很多事根本無法只用註解來解釋，甚至面對面用嘴巴講都說不清楚了。而註解寫好了，同事也常常不會去看，而是直接來問你，我也是一樣喜歡用問的，因為用問的遠遠比自己閱讀要來的快，那麼還有必要寫註解嗎？怎樣的註解才算寫的有價值？怎麼寫比較好？
我憑個人淺薄的經驗以及書籍資料歸納出以下4點：
1. 比程式碼容易讀的註解
當你的註解敘述文字比程式碼還要多的時候，很多人的直覺都是寧願去看程式碼，直接從程式碼看出你的設計手法，這只是直覺，其實有可能還是註解比較好理解，但就是會本能的先去看字數少的那一邊，可見字數是很重要的，忙碌的工程師常常是很猴急的想看重點。想要節省字數的一個重要方法就是寫虛擬碼，因為一部分的註解依然是用程式碼表示，所以用字會比較少。例如下面的程式上面使用一段虛擬碼當註解，既可減少字數又可以說明你的想法，而不是只讓別人看到不知所云的數字，也不會去亂猜你沒事將x歸零是要做什麼，因為你已經將目的表達出來了。
/*
if( 裝置還存在 )
{
銷毀它
}
*/
if(x)
{
delete x;
x=0;
}
在外貌、字數差不多的情況下，你也會比較想閱讀中文對吧？
以前還超常看到這種方塊註解
//////////////////////////////////////////
// //
// main.cpp //
// //
//////////////////////////////////////////
可能是「code complete」這本書有特別批評這種寫法，所以現在比較少看到了，這種寫法的缺點就是不好整理，每次修改都要去對齊，有夠煩的，而且也無端的造成閱讀上的負擔，字數越多只會讀的越累，即使寫的東西並不艱澀也一樣，而且需要的編輯手續越多，你就會越懶的去維護。
不過下面這種ㄈ型註解還可以接受
靠文字編輯器的幫忙不會太費事
//////////////////////////////////////////
//
// main.cpp
//
//////////////////////////////////////////
2. 不要去說明程式碼已經說過的事
有時候真的是比較雞婆一點，像下面這樣細心的說明
// 開啟*.txt格式的檔案
int OpenFile(const char *name);
雖然沒有註解的話，別人不曉得格式限制，但是看一下範例程式應該就能明白才對，註解只幫了一點小忙，代價是字數又變多了，不划算！不如別寫。
如果想不出字數夠少的註解，那乾脆另外給個文件說明吧，還程式碼一個乾淨的畫面。
3.不要只想靠註解做解釋，程式碼也要協助說明
每個類別、函式、變數的命名也都有輔助說明的作用，只是命名太短太長都不好，有些工程師非常執著於self-documenting的概念，也就是「程式碼即是文件」的作風，僅僅只用函式名稱來說明函式可說是種理想，有些人為了達成這個理想所以函式名稱超級長，幾乎是個完整的句子，那樣也只是造成閱讀困難好嗎。所以我們對命名的期望是盡量簡短，但是要盡可能足以說明自身用途，想要達成這個目標，基本上有兩個方向：
1.將函式拆分出更小的函式，函式越短你越容易給出恰當的命名。
2.用類別跟成員函式的名稱做聯合說明。
例如
Call(100);
這樣寫根本沒人知道這個函式的意義，但是成員函式的話還有類別名稱可供參考，兩個名字合起來就足以說明了。
phone.Call(100);
一個類別最好只有一個核心目標，圍繞在類別上面的成員就可以用很簡短的命名了，類別名稱也可以變的簡短，因為讀者還可以從眾成員名稱去猜測類別的功能，等於是用類別跟眾成員的名稱來聯合做出說明，字數夠多但是看起來不會繁雜，總之好的架構也會提高可讀性。
有一種常見的糟糕寫法，企圖依賴註解來做解釋，程式碼卻沒幫上忙，如下所示：
/// 這是程式進入點，參數1：執行程式時後面接了多少個字串，參數2：字串陣列
int main(int avg,char **avrg);
參數名稱有寫跟沒寫一樣，目光還要在註解跟程式碼之間移來移去，眼睛會累的啊，為什麼不這樣寫：
/// 這是程式進入點
int main(
int count, ///< 執行程式時，後面接了多少個字串
char** strings ///< 字串陣列
);
參數名稱盡量透露自己是什麼東西，而非什麼都交給註解解釋，排版上讓註解直接寫在參數後面不是好看多了嗎？這寫法是doxygen也支援的。
※不過我不會推薦你一定要使用doxygen，現代IDE對閱讀程式碼的輔助支援已經夠好了
4.不是任何說明都要塞到程式碼
其實絕大多數的說明文件都不適合以註解的形式存在，必須另外寫一份規格記錄來說明解釋，真正適合放在程式碼裡的註解都是針對一個物件、函式、變數或者行為來做解釋，或者在註解上告知讀者要參閱哪份文件的第幾頁，而最棒的使用說明文件就是範例程式，所以範例上的註解常常特別多。"Don’t comment bad code—rewrite it."
- Brian W. Kernighan and P. J. Plaugher
“Truth can only be found in one place: the code.”
- Robert C. Martin
