在编写 C# 代码时, 你需要遵循以下编码规范. 这些规范仅针对单个 .cs 文件内部的规则, 不涉及仓库结构, CI, 解决方案级约束.
运行时/框架级别: .NET 10. 语言级别: C# 14, 使用可用的最高版本 C# 的最新语法与表达能力. 可空性: 必须启用 #nullable enable; 禁止默默接受 null, 是否允许 null 必须在类型与文档中明确. 风格总原则: 代码即文档. 除 XML 文档注释外, 尽量不写任何注释; 非 XML 注释, 包括 // 或 /* */, 原则上禁止, 仅允许在无法通过代码结构表达关键原因 why 时, 用极少文字解释, 并且要求可追溯, 例如设计决策编号, 问题编号, 变更原因标识, 但不输出真实链接.
XML 文档注释覆盖范围, 强制: 本文件内的命名空间, 类型, 包括 class, struct, record, interface, enum, delegate, 枚举成员, 构造函数, 方法, 包括扩展方法, 属性, 字段, 包括 private, 事件, 运算符, 显式接口实现成员, 均必须具备 XML 文档注释. 不得以私有成员不重要为理由省略; 若成员确属内部细节, 也必须用简短 summary 明确其职责边界.
文档注释必须包含的内容, 按对象类型约束: 命名空间/文件头: 必须给出文件级信息, 包括文件职责, 作者, 最后修改日期, 以及该命名空间的语义边界. C# 无独立文件级 XML doc 语法, 因此将文件头信息写在命名空间的 XML doc 中承载. 作者固定为 WaterRun; 最后修改日期写为 2026-01-27, 示例日期按最新日期替换, 并规定每次修改该文件时必须更新为当天且保持作者为 WaterRun. 类型, 包括 class, struct, record, interface, enum, delegate: 必须包含 <summary>, 用一句话说明是什么 + 目的, 并在 <remarks> 中写明关键不变量, 线程安全结论, 默认不线程安全, 副作用边界, 使用约束; 若类型是抽象层, 包括接口或基类, 需描述契约而非实现细节. 方法/构造函数: 必须包含 <summary>, 所有参数的 <param>, 说明参数语义, 单位/范围, 是否允许 null, 边界条件, <returns>, 说明返回值语义, void 则省略 returns, 所有可预期异常的 <exception>, 说明异常类型 + 触发条件; 泛型方法必须包含每个 <typeparam>; 异步方法必须在 <remarks> 明确取消语义, 即 CancellationToken 的行为, 与完成语义, 即是否幂等, 是否可重入, 是否有 I/O. 属性: 必须包含 <summary> 与 <value>, 说明读写语义, 默认值, 是否延迟计算, 线程安全与副作用; 若 setter 会校验或抛异常, 必须在 <exception> 中声明. 字段/常量: 必须包含 <summary>, 说明该字段存在目的, 生命周期, 是否只读, 是否缓存, 是否线程相关; const 需说明语义与单位/范围. 事件: 必须包含 <summary> 与 <remarks>, 说明触发时机, 线程上下文, 是否可能重入, 订阅/取消订阅注意事项. 运算符/转换: 必须包含 <summary>, 参数与返回语义, 可能异常与不变量影响. 示例与引用: 公共 API 建议包含 <example>; 引用其他符号时使用 <see cref="..."/> / <seealso/>, 避免纯文本提及类型名导致工具无法解析.
XML 文档注释模板, 必须按此风格书写, 内容用中文, 短句, 可审计, 避免空话.
文件头, 承载文件信息: /* * 应用程序配置管理 -- 一句话简述 * 提供用户设置项与硬编码常量的统一访问入口, 支持持久化存储 -- 更多的介绍 * * @author: WaterRun -- 作者 * @file: Static/AppConfig.cs -- 基于源码目录的文件路径 * @date: 2026-01-27 -- 更新时间, 每次修改更新为最新 */
类型: ///
方法/构造函数, 含 async: ///
属性: ///
枚举与枚举成员: ///
命名规范, 强制: 公开类型与公开成员使用 PascalCase; 参数与局部变量使用 camelCase; 私有字段使用 _camelCase; 接口以 I 前缀, 例如 IUserRepository; 异常类型以 Exception 后缀; 特性类型以 Attribute 后缀; 异步方法以 Async 后缀; 布尔命名采用可读断言, 例如 isEnabled, hasValue, canRetry; 集合使用复数名, 例如 items, users, entries; 避免无意义缩写与匈牙利命名. 文件名应与该文件的主要公开类型名一致; 原则上一个 .cs 文件仅包含一个公开顶级类型, 其余辅助类型必须 internal 或 file-local, 并与主类型强耦合.
布局与可读性, 强制: 必须使用 file-scoped namespace; using 指令集中放在文件顶部且排序稳定; 控制流优先使用 guard clause 早返回以减少嵌套; 所有 if, for, foreach, while, switch 分支必须使用花括号; 不允许依赖缩进猜测逻辑; 表达式拆分以语义边界为准, 避免过长链式调用造成审计困难; 当类型承载业务语义时使用显式类型声明, 当右侧类型显然可见且不削弱语义时可用 var.
现代 C# 语法使用要求, 在不降低可维护性的前提下优先采用: 优先使用 pattern matching, 包括 is/not 与 switch 表达式, 表达分支意图; 优先使用 target-typed new, collection expressions, required members, init-only 属性, records, 适用于值语义与不可变数据, 提升表达力; 优先使用 primary constructors, 适用于依赖注入与纯数据载体, 但不得牺牲不变量校验与文档完整性; 允许使用 file-local 类型, 即 file 修饰符, 限定文件内实现细节边界; 可用时使用 throw expression 与 ArgumentNullException.ThrowIfNull 表达契约失败; 异步必须使用 Task / Task<T>, 除事件处理器外禁止 async void; 可取消操作必须接收 CancellationToken, 通常作为最后一个参数, 并在文档中定义取消语义; 不得通过忽略或吞掉异常来保证流程继续, 错误必须以异常或显式结果类型表达.
契约与异常, 强制: 所有不允许 null 的引用类型参数必须进行运行时校验; 范围与状态约束必须以语义明确的异常表达, 并在 <exception> 中声明触发条件; 异常不得作为常态控制流; 对可预期失败优先使用 TryXxx 或显式结果类型; 不得泄漏内部实现细节到公共异常消息中; 日志不得记录敏感信息, 包括密钥, 令牌, 个人身份, 支付等.
输出要求: 你在生成代码时必须严格遵循上述规范; 你在解释规范时保持冷静客观, 不输出与本规范无关的工程级内容; 你不得用列表或项目符号组织最终规范文本, 但此 Prompt 本身可以作为约束描述存在.
编写的代码善于使用 LINQ. 注意注释的各项内容使用中文文本.