bing-framework/bing.netcore/chinese-comments

中文注释规范

在生成或修改 C#/.NET 项目代码时，请自动补全中文 XML 注释。

必须补全的对象

• Controller 与 Action
• class / interface / enum / record / struct / delegate / event
• public / protected / internal / private 方法
• 构造函数
• DTO / Entity / Options
• public / protected / internal / private 属性
• 字段、常量、缓存键

注释要求

1. 使用简体中文。
2. 注释应描述业务含义，不要只翻译名称。
3. public、protected、internal、private 方法必须补全 <summary>、<param>、<returns>。
4. 枚举类型和枚举成员都要补全注释。
5. DTO、实体、控制器、应用服务必须优先补全注释。
6. 重要 private 字段和常量建议补充注释。
7. 保持代码格式化，不要破坏原有逻辑。
8. 如果发现已有注释质量较差，请优化为更准确的中文注释。
9. 对于复杂的业务逻辑，建议在方法体内添加必要的注释，解释关键步骤和算法。
10. 对于公共 API，建议在注释中包含示例代码或使用场景，以便其他开发者理解和使用。
11. 对于涉及到性能优化的代码段，建议在注释中说明优化的原因和预期效果。
12. 对于涉及到异常处理的代码段，建议在注释中说明可能抛出的异常类型及其处理方式。
13. 对于涉及到多线程或异步操作的代码段，建议在注释中说明线程安全性和异步行为的注意事项。
14. 对于涉及到外部依赖或第三方库的代码段，建议在注释中说明依赖的版本和使用方式。
15. 对于涉及到配置项或环境变量的代码段，建议在注释中说明配置的作用和默认值。
16. 对于涉及到安全性或权限控制的代码段，建议在注释中说明安全策略和权限要求。
17. 对于涉及到数据验证或输入校验的代码段，建议在注释中说明验证规则和错误处理方式。
18. 对于涉及到日志记录或监控的代码段，建议在注释中说明日志级别和监控指标。
19. 对于返回 Task 的返回值，则无需补充 <returns> 注释。

风格要求

• 简洁、专业、准确
• 符合企业级 .NET 项目风格
• 与 ABP / DDD / CQRS 场景兼容
• 优先体现业务用途，而非字面翻译

执行要求

当发现缺失注释时，请顺手补齐； 当发现已有注释质量较差时，请优化为更准确的中文注释。