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

Question

I'm very disciplined in writing detailed summaries of interfaces, classes, properties and methods. It's while I have in focus to share my code to anyone beeing able to read without any expenses in unnecessary explanations. I'm following a personal code guideline to ensure consistency.

Assume following interface ...

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

Assume following class ...

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. While a car serial number normally mustn't change its setter is private.
2. While the setter can be accessed in the abstract its documented as settable.
3. Implementing against the interface shows the documentation of the getter only.
4. Implementing against the abstract shows the setter too, but this one isn't accessible.

So my question is how to write proper summaries to not confuse the developers whose are using my libraries. I'm interested in your best practices to have a proper solution.

EDIT

Car serial number is a translation from german to english for the unique number of the chassis. It may not matches the best translation.

It's just a close example. Imagine a new BMW has been produced in the facility and gets its unique serial number. You derive a class BMW from CarAbstract, create it with an overwritten constructor but by passing the unique car serial number, too. By calling the base constructor and passing this number you're using the implementation of the abstract.

Imagine a use case where you need to access the car serial number in the derived BMW class. So the code assist shows you the comment of the property of the CarAbstract class. Someone may be confused to see there should be a setter, but there's not while it's private.

EDIT

By having a IList<CarInterface> you could iterate through several cars and read the car serial number. While typecasting to CarInterface the code assist shows you the comment of the interface with a summery of the getter only.

Answer 1

I suggest to use term "immutable".

Immutable usually describes property only set in constructor and not changeable so it seems fit to what you are asking.