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


19

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.


Sejujurnya satu-satunya komentar yang memberi saya yang tidak ada dalam kode (dengan asumsi ini adalah anggota Pengguna) adalah bahwa id itu unik. jadi tidak ada yang 'perlu'.
jk.

@ Thomas - sudahkah Anda menginstal plugin GhostDoc ? itu akan menghasilkan komentar XML yang baik untuk Anda jika Anda menggunakan nama properti yang bagus untuk memulai dan secara otomatis meletakkan gets or setsatau getstergantung pada pengakses properti.
Trevor Pilley

@ Trevor - Saya sudah menginstalnya. Saya hanya berpikir apakah saya harus mengubah templatnya dan menghapus "Gets or sets" atau tidak :). Ini adalah plugin yang bagus.
Tomas

Selamat datang di dunia tanpa dokumen .
Kolonel Panic

Jawaban:


28

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:

masukkan deskripsi gambar di sini

Demikian juga saat melihat dokumentasi kami juga tidak yakin:

masukkan deskripsi gambar di sini masukkan deskripsi gambar di sini masukkan deskripsi gambar di sini

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.

masukkan deskripsi gambar di sini


Terima kasih atas jawaban yang menyeluruh. Saya pikir ini sayangnya keterbatasan Visual Studio IDE. Saya telah memikirkannya dan saya berpikir bahwa intellisense dapat menunjukkan kepada Anda properti mana, misalnya, get-hanya dalam konteks saat ini. Sangat tidak nyaman untuk membengkokkan dokumentasi agar sesuai dengan lingkungan pengembangan tertentu. Namun saya masih berpikir bahwa Visual Studio dan C # sangat erat terkait sehingga ini mungkin solusi yang tepat.
Tomas

1
@ Thomas Saya setuju bahwa Visual Studio harus membuat lebih banyak perbedaan. Tentu saja dengan senang hati memberi saya garis berlekuk merah begitu saya menggunakan properti secara tidak benar.
Mike

2

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.


2

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.


1

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.

Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.