You need to enable JavaScript to run this app.
优惠活动
大模型
产品
解决方案
定价
更多

C#文档中如何引用其他属性以支持重构同步?

问题描述

现有如下C#类:

public sealed class Person 
{
  public string FirstName { get; set; }
  public string LastName { get; set; }

  public string DisplayName => $"{FirstName} {LastName}";
}

需要为DisplayName属性编写文档注释,当前写法如下:

/// <summary>
/// 由FirstName和LastName组成的空格分隔字符串
/// </summary>
public string DisplayName => $"{FirstName} {LastName}";

问题在于:如果把LastName重命名为FamilyName,代码可正常编译,但文档注释仍会引用已不存在的LastName属性。想知道是否存在类似如下伪语法的写法:

/// <summary>
/// 由<prop=FirstName>和<prop=LastName>组成的空格分隔字符串
/// </summary>

能让重构代码时文档同步更新,或让编译器针对这种文档与代码不一致的情况给出警告/错误?

解决方案
  • 使用标准XML文档注释的<see>标签
    C#原生支持用<see cref="成员名称"/>标签在文档注释中引用代码元素。使用该标签替代直接书写属性名后,主流IDE(如Visual Studio、JetBrains Rider)的重命名重构功能会自动同步更新文档里的引用;部分静态分析工具还能检测无效的cref引用并给出警告。
    示例写法:

    /// <summary>
    /// 由<see cref="FirstName"/>和<see cref="LastName"/>组成的空格分隔字符串
    /// </summary>
    public string DisplayName => $"{FirstName} {LastName}";
    
  • 启用静态分析规则
    开启相关代码分析规则(如CA1200:避免使用cref标签的重载形式,或专门检测无效XML注释引用的规则),当文档中的cref指向不存在的成员时,编译器会抛出警告或错误,强制你同步更新文档内容。

  • 依赖IDE的重构支持
    只要使用标准的<see cref="..."/>标签,Visual Studio、JetBrains Rider等主流IDE在对类成员执行重命名操作时,会自动扫描所有XML文档注释中的引用并同步更新,确保文档与代码的一致性。

内容的提问来源于stack exchange,提问作者Wouter Vandenputte

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.08.13 22:35:27