自己總結的C#編碼規範--5.如何寫好注釋篇

標籤：style   blog   http   color   使用   strong   io   檔案   

本文是讀完前言中提到的幾本書後，結合自身的想法總結出來的如何寫好注釋的一些比較實用的方法：

• 如何寫好注釋
• 避免使用不明確的代詞

有些情況下，"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)

上面的注釋不是很精確，因為有很多定義行的方式，下面幾種情況這個方法的傳回值無法根據注釋快速的判斷出來。

1. ""(空檔案)——0或1行？
2. "hello"——0或1行？
3. "hello\n"——1或2行？
4. "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)

這條注釋不是很精確，因為它不能回答下面的問題

1. 是只有按charsToRemove中順序的字元才會被移除，還是無序的charsToRemove也會被移除？
2. 如果在開頭和結尾有多個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。所以在更改代碼後，記得要更新所更改代碼的注釋，使其表達最新代碼的含意。

• 只有能讓別人讀懂的注釋才是合格的注釋

當自己不確定自己的注釋是否合格時，請周圍的同事讀下你的注釋，看他讀完注釋後說出的想法是否是你想要表達的，是否有資訊遺漏和誤解等。