本文是讀完前言中提到的幾本書后，結合自身的想法總結出來的如何寫好注釋的一些比較實用的方法。
另外本文是上一篇 注釋篇 的一個補充
-
如何寫好注釋
-
避免使用不明確的代詞
有些情況下，"it", "this"等代詞指代很容易產生歧義，最安全的方式是不要使用將所有可能產生歧義的代詞替換成實際指代的詞。
如：//Insert the data into the cache,but check if it's too big first.
"it"是指"data"還是"cache"? 在讀完剩下的代碼前誰也不知道指代的是誰。那還要注釋做什么？替換成要指代的詞后讀者就可以直接了當的知道接下來的代碼要做什么了。
//Insert the data into the cache,but check if the data is too big first.
-
精確描述方法的行為
注釋一定要精確的描述方法的行為。避免由於注釋不准確而造成的誤調用。
如你寫了一個方法統計文件中的行數
//Return the number of lines in this file
public long CountLinesInFile(string fileName)
上面的注釋不是很精確，因為有很多定義行的方式，下面幾種情況這個方法的返回值無法根據注釋快速的判斷出來。
- ""(空文件)——0或1行？
- "hello"——0或1行？
- "hello\n"——1或2行？
- "hello\n\r world\r"——2、3或4行？
假設該方法的實現是統計換行符的（\n）的個數，下面的注釋就要比原來的注釋更好些。
//Count how many newline symbols('\n') are this file
這條注釋包含更多的信息。讀者可以知道如果沒有換行符，這個函數會返回0。讀者還知道回車符（\r）會被忽略。
-
用輸入輸出例子來說明特殊的情況
對於注釋來講，一個精挑細選的例子比千言萬語還要有效，而且更加直白有效，閱讀速度更快。
如： /// <summary>
/// Remove the suffix/prefix of charsToRemove from the input source
/// </summary>
public string StripPrefixAndSuffix(string source, string charsToRemove)
這條注釋不是很精確，因為它不能回答下面的問題
- 是只有按charsToRemove中順序的字符才會被移除，還是無序的charsToRemove也會被移除？
- 如果在開頭和結尾有多個charsToRemove會怎樣？
而一個好例子就可以簡單直白的回答這些問題：
/// <summary>
/// Example: StripPrefixAndSuffix("abbayabbazbaba","ab") returns "yababz"
/// </summary>
-
適當的使用具名函數
假設你看見這樣的函數調用：
ConnectMailServer(100,false);
因為直接傳入的是數值和bool值，使得這個調用很難理解，在這種情況下可以使用C#的具名函數以便代碼閱讀者快速知道這兩個參數的含意。
假設函數是這樣的：public void ConnectMailServer(int timeout_s, bool useEncryption)
那我們可以這樣使用具名函數:
ConnectMailServer(timeout_s: 100, useEncryption: false);
代碼閱讀者一眼就能看出這兩個參數的作用。
-
使用通用專有名詞
代碼的閱讀者和調用者都是程序員，程序員間有大量的專有名詞可以用來描述一些模式和解決方案，使用這些詞，可以簡單明了的闡述你代碼的含意。
假設你原來的注釋是這樣的：
那么你完全可以簡單的說：
//This class acts as a caching layer to the database.
程序員一看caching layer就明白這個類是做什么的了。而且就算新手不明白，你的注釋也很難給他講明白的，還不如給他個關鍵詞，讓他自己去Google或向別人請教。這樣的效果比你的注釋會好的多。
-
更新代碼時記得更新注釋
再好的注釋也會隨着內容的更改而變得越來越沒有意義，有時候甚至會對讀者造成誤導，產生不必要的bug。所以在更改代碼后，記得要更新所更改代碼的注釋，使其表達最新代碼的含意。
-
只有能讓別人讀懂的注釋才是合格的注釋
當自己不確定自己的注釋是否合格時，請周圍的同事讀下你的注釋，看他讀完注釋后說出的想法是否是你想要表達的，是否有信息遺漏和誤解等。