所有 public 和 internal 成员必须有中文 XML 文档注释。scripts/check-xml-comments.mjs 脚本在 CI 中强制执行这一约定。

基本规则

GenerateDocumentationFile

Directory.Build.props 启用文档文件生成：

<GenerateDocumentationFile>true</GenerateDocumentationFile>
<NoWarn>CS1591;CS8632;CS8618</NoWarn>

CS1591（缺少 XML 注释）被设为 NoWarn，但脚本门禁比编译器更严格。

三行格式

每个公开成员至少有三行 XML 注释：<summary> + <param> + <returns> 或 <remarks>：

/// <summary>
/// 创建支付订单
/// </summary>
/// <param name="request">支付下单请求</param>
/// <param name="ct">取消令牌</param>
/// <returns>支付下单结果</returns>
Task<PaymentResult<PaymentOrderResult>> CreateOrderAsync(PaymentOrderRequest request, CancellationToken ct = default);

中文描述

描述用中文，说明”做什么”而非”怎么做”：

/// <summary>
/// 查询支付状态
/// </summary>
/// <remarks>
/// <para>返回值的 Status 字段为 Success / Pending / Closed。</para>
/// </remarks>
/// <param name="outTradeNo">商户订单号</param>
/// <param name="ct">取消令牌</param>
/// <returns>支付状态查询结果</returns>

#region 组织

代码使用 #region 块组织结构：

public sealed class AlipayPaymentProvider : IPaymentProvider
{
    #region Constants
    private const string MethodAppPay = "alipay.trade.app.pay";
    // ...
    #endregion

    #region Fields & Constructor
    private readonly AlipayHttpClient _httpClient;
    // ...
    #endregion

    #region IPaymentProvider
    public string Code => PaymentProviderCode.Alipay;
    // ...
    #endregion

    #region Helpers
    private static Dictionary<string, string> BuildBizContent(...) { ... }
    #endregion
}

常见 region 名称：Members、Configuration、Properties、Factory Methods、Constants、Helpers、IDisposable。

字段注释

私有字段也需要 XML 注释，说明保存的运行状态：

/// <summary>
/// 保存 <c>_httpClient</c> 在 <c>AlipayPaymentProvider</c> 中的运行状态
/// </summary>
private readonly AlipayHttpClient _httpClient;

参数注释

<param> 的描述简短明确：

/// <param name="outTradeNo">商户订单号</param>
/// <param name="ct">取消令牌</param>

禁止的内容

占位文本（如 <summary>TODO</summary>）
重复方法名的描述（如 CreateOrderAsync 的注释写”CreateOrderAsync”）
英文描述（除非是专有名词）