C#代碼風格指南

參考資料： asp.net 主頁倉庫

代碼風格 —— 通常原則

最通用的指導原則是咱們使用全部的VS默認設置的代碼格式，除了咱們把系統命名空間放在其餘命名空間以前（這在VS中是默認的，可是在VS的更新版本中已經改變了）。

1. 使用四個空格縮進（不用Tab）
2. 私有字段使用_camelCase
3. 除非必要，避免使用this.
4. 始終指定成員的可見性，即便你將使用的可見性和默承認見性一致
5. 開放的大括號({)要另起一行
6. 你可使用任何可用的語言特性，可是你要保持代碼易讀、易於維護
   • 舉一個反例：public (int, string) GetData(string filter) => (Data.Status, Data.GetWithFilter(filter ?? throw new ArgumentNullException(nameof(filter))));
   • 這是一條很難讀懂的語句

使用var聲明變量

只要編譯器容許，那麼儘量的使用var聲明變量，好比下面的代碼：

var fruit = "Lychee";
var fruits = new List<Fruit>();
var flavor = fruit.GetFlavor();
string fruit = null; // can't use "var" because the type isn't known (though you could do (string)null, don't!)
const string expectedName = "name"; // can't use "var" with const

反面例子：

string fruit = "Lychee";
List<Fruit> fruits = new List<Fruit>();
FruitFlavor flavor = fruit.GetFlavor();

在公共API中只使用完整的單詞或通用/標準縮寫

公共名稱空間，類型名稱，成員名稱和參數名稱必須使用完整的單詞或通用/標準縮寫。

示例：

public void AddReference(AssemblyReference reference);
public EcmaScriptObject SomeObject { get; }

反例：

public void AddRef(AssemblyReference ref);
public EcmaScriptObject SomeObj { get; }

使用C#類型關鍵字，而不是.Net Type名

例如：

public string TrimString(string s) {
    return string.IsNullOrEmpty(s)
        ? null
        : s.Trim();
}

var intTypeName = nameof(Int32); // can't use C# type keywords with nameof

反例：

public String TrimString(String s) {
    return String.IsNullOrEmpty(s)
        ? null
        : s.Trim();
}

異步方法模式

默認狀況下，全部異步方法都必須具備Async後綴

擴展方法模式

通常的規則是：若是一個普通的靜態方法就足夠了，避免使用擴展方法。

擴展方法一般對建立可鏈式調用的方法很是有用，例如，在構建複雜對象或建立查詢時。

內部擴展方法是容許的，但要記住先前的指導方針：拍拍胸脯問問本身，擴展方法是否真的是最合適的模式。

擴展方法類的名稱空間一般應該是表示擴展方法功能的名稱空間，而不是目標類型的名稱空間，一個常見的例外是中間件擴展方法的命名空間一般老是與IAppBuilder的命名空間相同。

擴展方法容器（也稱爲「sponsor type」）的類名一般應遵循<Feature>Extensions，<Target><Feature>Extensions或<Feature> <Target>Extensions的模式。例如：

namespace Food {
    class Fruit { ... }
}

namespace Fruit.Eating {
    class FruitExtensions { public static void Eat(this Fruit fruit); }
  OR
    class FruitEatingExtensions { public static void Eat(this Fruit fruit); }
  OR
    class EatingFruitExtensions { public static void Eat(this Fruit fruit); }
}

在編寫接口的擴展方法時，sponsor type名稱不能以I開頭。

Doc comments

編寫代碼的人將寫入Doc comments，僅限公共API。非公開類型不須要Doc comments。

注：public意味着下游能夠調用，因此它包含受保護的API。可是，一些公共API可能仍然是「僅供內部使用」，但因爲技術緣由須要公開。咱們仍然會針對這些API提供文檔，可是會根據狀況進行記錄。

常量定義

常量的定義使用帕斯卡命名法，避免使用全大寫命名
例如：

public const string HashKey="ie832js834u9f9wq3h";

錯誤：

public const string HASH_KEY="ie832js834u9f9wq3h";

縮寫算做單詞，避免使用全字符大寫

例如：

var api ="...
public void FindApi(...

錯誤：

var API ="...
public void FindAPI(...

例如常見的WTO是縮寫，可是建議算做單詞，寫爲 Wto、wto而不是WTO