Apakah "Mendapat atau menetapkan .." diperlukan dalam dokumentasi XML properti?

Saya mencari rekomendasi praktik terbaik untuk komentar XML di C #. Saat Anda membuat properti, sepertinya dokumentasi XML yang diharapkan memiliki bentuk berikut:

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

Tetapi karena tanda tangan properti sudah memberi tahu Anda operasi apa yang tersedia untuk klien eksternal kelas (dalam hal ini keduanya getdan set) saya merasa seperti komentar yang terlalu cerewet dan bahwa mungkin yang berikut ini sudah cukup:

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

Microsoft menggunakan formulir pertama sehingga sepertinya itu adalah konvensi tersirat. Tapi saya pikir yang kedua lebih baik karena alasan yang saya nyatakan.

Saya mengerti bahwa pertanyaan ini adalah keahlian untuk ditandai sebagai tidak konstruktif, tetapi jumlah properti yang harus dikomentari sangat besar dan saya percaya bahwa pertanyaan ini memiliki hak untuk berada di sini.

Saya akan menghargai ide atau tautan apa pun ke praktik yang direkomendasikan resmi.

Tanda tangan dapat memberi tahu potongan kode lain operasi apa yang tersedia; namun, mereka tidak ditunjukkan dengan jelas kepada pembuat kode saat dia bekerja dan dokumentasi XML dimaksudkan untuk dikonsumsi orang dan bukan kompiler.

Ambil kelas ini misalnya:

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

Ketika intellisense ditarik untuk mengakses salah satu properti ini, tidak ada indikasi yang dapat ditulis, dibaca, atau keduanya:

Demikian juga saat melihat dokumentasi kami juga tidak yakin:

Karena itu kami menambahkan mendapat atau set , mendapat , atau set untuk membuatnya lebih mudah pada programmer saat menulis kode. Tentunya tidak akan menulis blok kode besar yang membaca dan memproses beberapa data hanya untuk mengetahui bahwa Anda tidak dapat menulis data itu kembali ke properti seperti yang diharapkan.

StyleCop menggunakan Gets or Sets ...notasi yang diberlakukan dengan aturan SA1623 .

Halaman tertaut mencantumkan case lain yang belum Anda daftarkan:

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

Opsi lain yang Anda daftarkan adalah.

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

vs.

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

Yang tidak akan memberikan informasi tentang petunjuk Intellisense bahwa properti itu hanya baca, Anda bisa membuat konvensi untuk kasus ini juga, tetapi Gets ..., Gets or Sets...apakah pekerjaan itu baik-baik saja.

Ada juga varian lain yang tercantum pada aturan StyleCop yang jelas dengan menggunakan Gets or Sets...tetapi mungkin tidak tanpa.

Juga ketika menghasilkan dokumentasi dari sesuatu seperti Doxygen atau Sandcastle, notasi lengkap akan mendokumentasikan API (misalnya) dengan lebih baik.

Satu-satunya waktu saya menambahkan informasi tentang mendapatkan dan pengaturan properti di komentar XML adalah ketika tidak berperilaku seperti yang diharapkan (dapatkan dan set publik langsung).

Jika bersifat pribadi atau jika mengandung logika tambahan maka saya menyebutkannya, kalau tidak saya hanya mendokumentasikan maksud properti.

Saya akan lebih bahagia dengan versi yang lebih verbose.

Yang lain seperti memiliki komentar "increment counter" setelah, well, incrementing variabel counter.

Jelas ada Get and Set. Jika Anda memiliki setter pribadi, itu akan jelas karena Anda akan memiliki kata kunci pribadi.

Komentar harus menambah nilai, bukan hanya versi komentar dari apa kode sebenarnya.