Là các Gets Gets hoặc các bộ .. Cần thiết trong tài liệu XML của các thuộc tính?

Tôi đang tìm kiếm một đề xuất về một thực tiễn tốt nhất cho các nhận xét XML trong C #. Khi bạn tạo một thuộc tính, có vẻ như tài liệu XML dự kiến ​​có dạng sau:

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Nhưng vì chữ ký của tài sản đã cho bạn biết những thao tác nào có sẵn cho các máy khách bên ngoài của lớp (trong trường hợp này là cả hai getvà set) Tôi cảm thấy như các bình luận quá trò chuyện và có lẽ những điều sau đây là đủ:

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft sử dụng hình thức đầu tiên nên có vẻ như đó là một quy ước ngụ ý. Nhưng tôi nghĩ rằng cái thứ hai tốt hơn cho những lý do tôi đã nêu.

Tôi hiểu rằng câu hỏi này là một kỹ năng tuyệt vời để được đánh dấu là không mang tính xây dựng, nhưng số lượng tài sản mà người ta phải nhận xét là rất lớn và vì vậy tôi tin rằng câu hỏi này có quyền ở đây.

Tôi sẽ đánh giá cao bất kỳ ý tưởng hoặc liên kết đến thực tiễn khuyến nghị chính thức.

Chữ ký có thể cho biết các đoạn mã khác hoạt động có sẵn; tuy nhiên, chúng không được hiển thị rõ ràng cho người viết mã khi anh ta hoặc cô ta đang làm việc và tài liệu XML có nghĩa là để mọi người tiêu thụ chứ không phải là một trình biên dịch.

Lấy lớp này làm ví dụ:

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

Khi intellisense được kéo lên để truy cập vào một trong các thuộc tính này, không có dấu hiệu nào có thể được ghi vào, đọc từ hoặc cả hai:

Tương tự như vậy khi xem tài liệu chúng tôi cũng không chắc chắn lắm:

Vì vậy, chúng tôi thêm get hoặc bộ , get hoặc set để giúp lập trình viên dễ dàng hơn trong khi viết mã. Chắc chắn sẽ không viết một khối mã lớn chỉ đọc và xử lý một số dữ liệu để biết rằng bạn không thể ghi dữ liệu đó trở lại thuộc tính như mong đợi.

StyleCop sử dụng Gets or Sets ...ký hiệu mà nó thi hành theo quy tắc SA1623 .

Trang được liên kết liệt kê một trường hợp khác mà bạn chưa liệt kê:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

Các tùy chọn khác bạn liệt kê sẽ là.

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

đấu với

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

Điều này sẽ không cung cấp thông tin về gợi ý Intellisense rằng tài sản chỉ được đọc, bạn cũng có thể đưa ra một quy ước cho trường hợp này, nhưng Gets ..., Gets or Sets...công việc này có độc đáo không.

Ngoài ra còn có các biến khác được liệt kê trên quy tắc StyleCop rõ ràng bằng cách sử dụng Gets or Sets...nhưng có thể không có.

Ngoài ra, khi tạo tài liệu từ một cái gì đó như Doxygen hoặc Sandcastle, ký hiệu đầy đủ sẽ ghi lại API (ví dụ) tốt hơn.

Lần duy nhất tôi thêm thông tin về việc nhận và cài đặt một thuộc tính trong các nhận xét XML là khi nó không hoạt động như mong đợi (lấy và đặt công khai thẳng).

Nếu là riêng tư hoặc nếu chúng chứa logic bổ sung thì tôi đề cập đến chúng, nếu không tôi chỉ ghi lại ý định của tài sản.

Tôi sẽ hạnh phúc hơn với phiên bản dài dòng hơn.

Cái khác giống như có một nhận xét về "bộ đếm tăng" sau, tốt, tăng một biến số bộ đếm.

Rõ ràng là có một Get và Set. Nếu bạn có một trình thiết lập riêng tư, điều đó là hiển nhiên vì bạn sẽ có từ khóa riêng.

Nhận xét nên thêm giá trị, không chỉ là phiên bản nhận xét về mã thực sự là gì.