前言
之前工作中整理的一篇編碼規范。
代碼注釋
注釋約定
方法注釋
所有的方法都應該以描述這段代碼的功能的一段簡明注釋開始（方法是干什么）。這種描述不應該包括執行過程細節（它是怎么做的）
/// <summary>
/// 把對象類型轉化為指定類型
/// </summary>
/// <typeparam name="T">動態類型 </typeparam>
/// <param name="value">要轉化的源對象 </param>
/// <returns> 轉化后的指定類型的對象，轉化失敗引發異常。</returns>
public static T CastTo<T>(this object value)
代碼行注釋
如果某一功能需要多行代碼，並有多個邏輯結構，應在此代碼前添加注釋，說明此塊代碼的處理思路及注意事項等
注釋從新行增加，與代碼開始處左對齊
注釋雙斜線與注釋之間以空格分開，示例如下：
public void Dispose(){
// 如果連接已打開，則關閉連接並釋放資源
if(this.connection.State == ConnectionState.Open ){
this.connection.Close();
this.connection.Dispose();
}
}
變量注釋
變量需添加注釋，說明變量的用途
Class級變量使用///生成的Xml標簽格式的文檔注釋
/// <summary>
/// 文檔名稱
/// </summary>
public static string docName = "";
方法級的變量注釋可以放在變量聲明語句后，與上下行的注釋左對齊，注釋與代碼間以
Tab鍵分隔
public void CreateDoc() {
string docType = ""; //文檔類型
string author = ""; //作者
DateTime createDate = DateTime.Now; //創建世界
}
命名規范
命名基本約定
PascalCasing：
包含一個或多個單詞，每個單詞首字母大寫，其余小寫
使用范圍：命名空間、類、接口、方法、屬性、事件、非私有字段、枚舉值
namespace System.IO
public static class Console
public enum FileAccess
camelCasing：
包含一個或多個單詞，第一個單詞首字母小寫，其余單詞首字母大寫
使用范圍：方法參數、局部變量
public string GetName(int productId){
string productName = null;
}
_camelCasing：
"_"+camelCasing的方式
使用范圍：私有字段
private string _productName;
UPPER_CAPS：
包含多個單詞，每個單詞的所有字母大寫，單詞之間使用"_"連接
使用范圍：const常量
public const string DEFAULT_NAME = "default";
示例：
namespace ConsoleApp {
public delegate void SalesOutEventHandler();
public class Product {
public event SalesOutEventHandler OnSalesOut;
public Product GetProductById(int productId) {
return null;
}
private enum ProductType {
}
}
}
標識符命名約定
類和接口
類的名字使用名詞
避免使用單詞縮寫，除非是廣為人知的，比如：HTTP,IO
接口以I字母開頭
同一項目不同命名空間中的類，命名避免重復
方法
第一個單詞為動詞
返回值為bool類型，則加Is,Can,Try前綴
變量
盡量使用短而有意義的單詞
單字符變量名一般用於生命周期非常短的變量，如for,foreach中遞增變量可以被命名為i
如果變量表示集合，則變量名使用復數，如RowsCount
命名控件使用匈牙利命名法，前綴遵循同一個縮寫表
在帶單位的值變量后加“_camelCasing”格式的單位，如：public void CreateCache(int cacheSize_mb)
類型成員排列順序
類型成員的排列順序自上而下依次為：
字段： 私有字段、受保護字段
屬性： 私有屬性、受保護屬性、公有屬性
事件： 私有事件、受保護事件、公有事件
構造函數： 參數數量最少的構造函數，參數數量中等的構造函數，參數數量最多的構造函數
方法： 重載方法的排列順序與構造函數相同，從參數數量最少往下至參數最多
其他規范
代碼長度
每行代碼不宜過長，應在屏幕寬度之內，約為80-120個字符左右。換行規則如下：
在逗號后換行
在操作符后換行
在高層換行而不是在低層換行
換行后與上一行語句對齊
推薦寫法：
var n = a * b / (c - g + f) +
4 * z;
不推薦寫法：
var n = a * b / (c - g +
f) + 4 * z;
方法行數
每個方法的有效代碼行數（不包括注釋和空行）應保持在50行以內
空白
空行是為了將邏輯相關的代碼分塊，以便提高閱讀性
在以下情況使用兩個空行：
類聲明和接口聲明之間
兩個類聲明之間
枚舉與類聲明之間
在以下情況使用一個空行：
方法與方法、屬性與屬性之間
方法中變量聲明與語句之間
方法與方法之間
方法不同邏輯塊之間
類中屬性與方法、屬性與字段、方法與字段之間
注釋與它注釋的語句之間不空行，與其他語句之間空一行
在以下情況使用空格：
在VS編輯器中可以使用快捷鍵格式化代碼
參數列表的逗號后，
void UpdateDate(int a, int b)
二元操作符，a += b - c;
強制類型轉換后，c = (char) a;
代碼縮進
代碼縮進使用Tab鍵，不要使用空格，Tab鍵的寬度為4個字符，VS中設置如下：
【工具】-【選項】-【文本編輯器】-【C#】-【制表符】，選中【保留制表符】
代碼半展開
把花括號放在前一條語句的末尾，VS中設置如下：
【工具】-【選項】-【文本編輯器】-【C#】-【格式設置】-【新行】，取消右側所有勾選
附錄
注釋內容
| 項目 | 注釋內容 |
|---|---|
| 類 | 類的目的，開發歷史 |
| 接口 | 接口的目的，如何使用 |
| 字段/屬性 | 字段描述 |
| 方法注釋 | 方法作用，返回值，拋出的異常，調用的前提和后置條件 |
| 方法內部注釋 | 控制結構，復雜的代碼，處理順序 |
| 參數 | 用來做什么，約束，前提條件 |
| 局部變量 | 用處，目的 |
XML文檔注釋
MSDN文檔注釋標簽 https://msdn.microsoft.com/zh-cn/library/5ast78ax(v=vs.140).aspx
| 標記 | 說明 |
|---|---|
| <c> | 提供了一種將說明中的文本標記為代碼的方法 |
| <code> | 提供了一種將多行指示為代碼的方法 |
| <example> | 可以指定使用方法或其他庫成員的示例。一般情況下，這將涉及到<code>標記的使用。 |
| <exception> | 對可從當前編譯環境中獲取的異常的引用。 |
| <include> | 引用描述源代碼中類型和成員的另一文件中的注釋。 |
| <list> | 用於定義表或定義列表中的標題行。 |
| <para> | 用於諸如<summary>、<remarks> 或 <returns> 等標記內，使您將結構添加到文本中。 |
| <param> | 應當用於方法聲明的注釋中，以描述方法的一個參數。 |
| <paramref> | 提供了一種指示詞為參數的方法。 |
| <permission> | 將成員的訪問記入文檔。 |
| <remarks> | 用於添加有關某個類型的信息，從而補充由 <summary> 所指定的信息。 |
| <returns> | 應當用於方法聲明的注釋，以描述返回值。 |
| <see> | 從文本內指定鏈接。 |
| <seealso> | 對可以通過當前編譯環境進行調用的成員或字段的引用。 |
| <summary> | 應當用於描述類型或類型成員。 |
| <value> | 描述屬性。 |
VS常用快捷鍵
| 功能 | VS2010 | VS2013 | 說明 |
|---|---|---|---|
| 文檔格式化 | Ctrl+E, Ctrl+D | Ctrl+K, Ctrl+D | 格式化當前文檔 |
| 選定內容格式化 | Ctrl+E, Ctrl+F | Ctrl+K, Ctrl+F | 格式化選中內容 |
| 注釋 | Ctrl+E, Ctrl+C | Ctrl+K, Ctrl+C | 注釋當前行 |
| 取消注釋 | Ctrl+E, Ctrl+U | Ctrl+K, Ctrl+U | 取消注釋當前行 |
| 復制 | Ctrl+C | - | 復制光標所在行，不需要選中 |
| 剪切 | Ctrl+X | - | 剪切光標所在行，不需要選中 |
| 刪除 | Ctrl+L | - | 刪除光標所在行，不需要選中 |
| 折疊 | - | Ctrl+M, Ctrl+O | 折疊當前文檔 |
| 展開折疊 | - | Ctrl+M, Ctrl+L | 展開當前文檔 |
參考
MSDN開發語言和工具 https://msdn.microsoft.com/zh-cn/library/aa187916.aspx
C#語言規范 C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC#\Specifications\2052\CSharp Language Specification.docx