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;
    }
  }
}

虽然汽车序列号通常不能更改其设置者是私有的。
虽然可以在摘要中访问setter，但它可以记录为可设置。
针对界面的实现仅显示getter的文档。
对抽象的实现也显示了setter，但是这个不可访问。

所以我的问题是如何编写正确的摘要，以免混淆使用我的库的开发人员。我对您的最佳实践感兴趣，以获得适当的解决方案。

修改

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

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

想象一个用例，您需要访问派生的BMW类中的汽车序列号。因此代码帮助向您显示CarAbstract类的属性的注释。有些人可能会感到困惑，因为他们应该有一个制定者，但是在它是私人的时候却不会。

修改

通过拥有IList<CarInterface>你可以迭代几辆车并阅读汽车序列号。在对CarInterface进行类型转换时，代码帮助会向您显示界面的注释，只有getter的摘要。

Answer 1

我建议使用term＆＃34; immutable＆＃34;。

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

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

1 个答案: