这是本文档旧的修订版！
<markdown>
## 框架
.net 读 dot net
```csharp using System ; 引用头文件 namespace 控制台 ; 命名空间 【Program的命名空间就是：控制台】
class Program ; //class 用于声明一个类
```
使用中建议、类名称与文件名保持一样 尽量一个类一个文件
## 一、命名规范 ### 1. 大小写风格
- PascalCase
用于：类、接口、结构、枚举、属性、方法、事件、命名空间 例：`OrderService`、`GetUserInfo()`、`UserName`
- camelCase
用于：参数、局部变量 例：`userId`, `totalCount`
- 带下划线camelCase
用于：私有字段（Roslyn、.NET Runtime 推荐） 例：`_logger`, `_cache`
- SCREAMING_CASE
用于：常量、`static readonly` 字段 例：`DEFAULT_BUFFER_SIZE`;
### 2. 接口命名
- 接口必须以 I 开头
示例：`IList`, `ILoggerFactory`
### 3. 枚举命名
- 枚举成员：PascalCase - 不使用前缀（如 `Enum_`）
```csharp
enum FileState { Open, Closed, Locked }
```
### 4. 命名空间 - PascalCase - 公司或组织级前缀
示例：`Microsoft.Extensions.Logging`
—
## 二、代码布局与格式
### 1. 缩进与空白
- `, ; { }` 后加空格；方法调用括号内无空格
```csharp DoWork(item, index); ```
### 2. 大括号（Brace）风格 使用 Allman 风格（每个 `{` 独占一行）： ```csharp public void Run() {
...
} ```
### 3. 空行规则 - 成组代码块之间使用 1 行空行 - 方法之间留 1 行空行 - 不要连续多个空行
—
## 三、成员排序（微软推荐顺序） 类内部成员推荐顺序：
1. 常量 2. 静态字段 3. 字段 4. 构造函数 5. 属性 6. 事件 7. 方法 8. 嵌套类型
—
## 四、表达式与语言特性
### 1. var 使用 - 仅当类型明确或无关紧要时使用 var
```csharp var list = new List<int>(); // 类型明显 ```
- 如果不明显，使用显式类型：
```csharp int count = GetCount(); ```
### 2. 表达式体成员
- 适用于简单成员：
```csharp public int Count ⇒ _items.Count; public override string ToString() ⇒ Name; ```
### 3. Lambda 风格 - 简短 lambda 可在一行 - 多行 lambda 保持缩进
```csharp
items.Where(x =>
{
return x.Enabled;
});
```
—
## 五、可读性规范
### 1. 方法长度 - 尽量短小，一个方法保持单一职责
### 2. 参数顺序 - 必选参数在前，可选参数在后 - `CancellationToken` 必须是最后一个参数：
```csharp public Task RunAsync(int id, CancellationToken cancellationToken); ```
### 3. 布尔命名 - 使用肯定句：`isReady`, `hasValue`, `canExecute`
避免：`isNotValid`, `noItems`
—
## 六、注释规范
### 1. 文档注释 XML 公共 API 必须有 XML 注释： ```csharp / <summary> / 获取用户信息。 / </summary> public User GetUser(int id) { … } ``` ### 2. 行注释 只用于解释复杂逻辑，避免写显而易见的注释。 — ## 七、异常与错误处理 ### 1. 异常名称 继承 Exception 且名称以 Exception 结尾 ```csharp class InvalidConfigurationException : Exception { } ``` ### 2. 不要使用异常控制流程 避免： ```csharp try { … } catch { … } 控制逻辑 ``` 异常应该保留给意外情况，而不是正常控制流程。
因为异常的代价比较高
—
## 八、文件与项目结构
### 1. 每个类型单独一个文件 除非： - 小型私有辅助类 - 局部类型
### 2. 文件命名 文件名与主类名一致： ``` OrderService.cs ```
### 3. using 指令 按以下顺序分组——每组之间空一行：
1. System.* 命名空间 2. 第三方包 3. 当前项目命名空间
示例： ```csharp using System; using System.Collections.Generic;
using Newtonsoft.Json;
using MyApp.Core; ```
—
## 九、异步编程规范（微软官方 async 规则）
### 1. 异步方法必须以 Async 结尾 ```csharp public Task SaveAsync(); ```
### 2. 仅在使用 await 时将方法标记为 async
### 3. ConfigureAwait 库代码中使用： ```csharp await task.ConfigureAwait(false); ```
—
## 十、不可变性与集合规范
### 1. 优先使用只读字段 ```csharp private readonly ILogger _logger; ```
### 2. 公开集合使用 IReadOnlyList / IEnumerable 避免暴露可变集合类型。
—
</markdown>
张叶安