C#：为 getter 和 setter 的不同访问器编写属性摘要

Question

我在编写接口、类、属性和方法的详细摘要方面非常自律。在此期间，我专注于将我的代码分享给任何能够阅读的人，而无需任何不必要的解释费用。我遵循个人代码指南以确保一致性。

假设如下界面...

namespace CarFacility
{
  /// <summary>Represents the interface of all cars.</summary>
  public interface CarInterface
  {
    /// <summary>Gets the car serial number.</summary>
    string CarSerialNumber
    {
      get;
    }
  }
}

假设以下课程...

namespace CarFacility
{
  /// <summary>Represents the base class of all cars.</summary>
  public abstract class CarAbstract:
    CarInterface
  {
    /// <summary>Stores the car serial number.</summary>
    private string _carSerialNumber = string.Empty;

    /// <summary>Gets / sets the car serial number.</summary>
    public virtual string CarSerialNumber
    {
      get
      {
        string carSerialNumber = this._carSerialNumber;
        return carSerialNumber;
      }
      private set
      {
        this._carSerialNumber = value;
      }
    }

    /// <summary>Creates a new car with a unique serial number.</summary>
    /// <param name="carSerialNumber">The unique car serial number of the car.</param>
    public CarAbstract( string carSerialNumber )
    {
      this.CarSerialNumber = carSerialNumber;
    }
  }
}

1. 虽然汽车序列号​​通常不能更改，但它的设置器是私有的。
2. 虽然 setter 可以在摘要中访问，但它记录为可设置。
3. 针对接口实现仅显示 getter 的文档。
4. 根据摘要实现也显示了 setter，但这个不可访问。

所以我的问题是如何编写适当的摘要，以免混淆使用我的库的开发人员。我对您的最佳做法感兴趣，以便找到合适的解决方案。

编辑

汽车序列号​​是从德语到英语的翻译，用于底盘的唯一编号。它可能与最佳翻译不匹配。

这只是一个很好的例子。想象一下，在该设施中生产了一辆新的 BMW，并获得了其唯一的序列号。您从 CarAbstract 派生了一个 BMW 类，使用覆盖的构造函数创建它，但也传递唯一的汽车序列号​​。通过调用基本构造函数并传递此数字，您正在使用抽象的实现。

想象一个用例，您需要在派生的 BMW 类中访问汽车序列号​​。因此，代码辅助会向您显示 CarAbstract 类的属性的注释。有人可能会感到困惑，认为应该有一个 setter，但它是私有的。

编辑

通过IList<CarInterface>，您可以遍历几辆汽车并读取汽车序列号​​。在对CarInterface 进行类型转换时，代码辅助会向您显示接口的注释以及 getter 的摘要。

Answer 1

我建议使用术语“不可变”。

不可变通常描述仅在构造函数中设置且不可更改的属性，因此它似乎符合您的要求。