Apakah Dokumentasi XML Diperlukan Komentar?

Saya dulu penggemar yang membutuhkan komentar XML untuk dokumentasi. Sejak itu saya berubah pikiran karena dua alasan utama:

1. Seperti kode yang baik, metode harus jelas.
2. Dalam praktiknya, sebagian besar komentar XML adalah noise tidak berguna yang tidak memberikan nilai tambah.

Banyak kali kita hanya menggunakan GhostDoc untuk menghasilkan komentar umum, dan inilah yang saya maksudkan dengan noise yang tidak berguna:

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

Bagi saya, itu sudah jelas. Karena itu, jika ada instruksi khusus untuk dimasukkan, maka kita harus benar-benar menggunakan komentar XML.

Saya suka kutipan ini dari artikel ini :

Terkadang, Anda perlu menulis komentar. Tapi, itu harus menjadi pengecualian, bukan aturan. Komentar hanya boleh digunakan ketika mereka mengekspresikan sesuatu yang tidak bisa diungkapkan dalam kode. Jika Anda ingin menulis kode yang elegan, berusahalah untuk menghilangkan komentar dan alih-alih menulis kode self-documenting.

Apakah saya salah berpikir bahwa kita seharusnya hanya menggunakan komentar XML ketika kode tidak cukup untuk menjelaskan sendiri?

Saya percaya ini adalah contoh yang baik di mana komentar XML membuat kode cantik terlihat jelek. Dibutuhkan kelas seperti ini ...

public class RawMaterialLabel : EntityBase
{
    public long     Id                      { get; set; }
    public string   ManufacturerId          { get; set; }
    public string   PartNumber              { get; set; }
    public string   Quantity                { get; set; }
    public string   UnitOfMeasure           { get; set; }
    public string   LotNumber               { get; set; }
    public string   SublotNumber            { get; set; }
    public int      LabelSerialNumber       { get; set; }
    public string   PurchaseOrderNumber     { get; set; }
    public string   PurchaseOrderLineNumber { get; set; }
    public DateTime ManufacturingDate       { get; set; }
    public string   LastModifiedUser        { get; set; }
    public DateTime LastModifiedTime        { get; set; }
    public Binary   VersionNumber           { get; set; }

    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

... Dan mengubahnya menjadi ini:

/// <summary>
/// Container for properties of a raw material label
/// </summary>
public class RawMaterialLabel : EntityBase
{
    /// <summary>
    /// Gets or sets the id.
    /// </summary>
    /// <value>
    /// The id.
    /// </value>
    public long Id { get; set; }

    /// <summary>
    /// Gets or sets the manufacturer id.
    /// </summary>
    /// <value>
    /// The manufacturer id.
    /// </value>
    public string ManufacturerId { get; set; }

    /// <summary>
    /// Gets or sets the part number.
    /// </summary>
    /// <value>
    /// The part number.
    /// </value>
    public string PartNumber { get; set; }

    /// <summary>
    /// Gets or sets the quantity.
    /// </summary>
    /// <value>
    /// The quantity.
    /// </value>
    public string Quantity { get; set; }

    /// <summary>
    /// Gets or sets the unit of measure.
    /// </summary>
    /// <value>
    /// The unit of measure.
    /// </value>
    public string UnitOfMeasure { get; set; }

    /// <summary>
    /// Gets or sets the lot number.
    /// </summary>
    /// <value>
    /// The lot number.
    /// </value>
    public string LotNumber { get; set; }

    /// <summary>
    /// Gets or sets the sublot number.
    /// </summary>
    /// <value>
    /// The sublot number.
    /// </value>
    public string SublotNumber { get; set; }

    /// <summary>
    /// Gets or sets the label serial number.
    /// </summary>
    /// <value>
    /// The label serial number.
    /// </value>
    public int LabelSerialNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order number.
    /// </summary>
    /// <value>
    /// The purchase order number.
    /// </value>
    public string PurchaseOrderNumber { get; set; }

    /// <summary>
    /// Gets or sets the purchase order line number.
    /// </summary>
    /// <value>
    /// The purchase order line number.
    /// </value>
    public string PurchaseOrderLineNumber { get; set; }

    /// <summary>
    /// Gets or sets the manufacturing date.
    /// </summary>
    /// <value>
    /// The manufacturing date.
    /// </value>
    public DateTime ManufacturingDate { get; set; }

    /// <summary>
    /// Gets or sets the last modified user.
    /// </summary>
    /// <value>
    /// The last modified user.
    /// </value>
    public string LastModifiedUser { get; set; }

    /// <summary>
    /// Gets or sets the last modified time.
    /// </summary>
    /// <value>
    /// The last modified time.
    /// </value>
    public DateTime LastModifiedTime { get; set; }

    /// <summary>
    /// Gets or sets the version number.
    /// </summary>
    /// <value>
    /// The version number.
    /// </value>
    public Binary VersionNumber { get; set; }

    /// <summary>
    /// Gets the lot equipment scans.
    /// </summary>
    /// <value>
    /// The lot equipment scans.
    /// </value>
    public ICollection<LotEquipmentScan> LotEquipmentScans { get; private set; }
}

Jika komentar Anda hanya terlihat seperti ini:

/// <summary>
/// Gets or sets the sublot number.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Maka ya, mereka tidak terlalu berguna. Jika mereka membaca sesuatu seperti ini:

/// <summary>
/// Gets or sets the sublot number.
/// Note that the sublot number is only used by the legacy inventory system.
/// Latest version of the online inventory system does not use this, so you can leave it null. 
/// Some vendors require it but if you don't set it they'll send a request for it specifically.
/// </summary>
/// <value>
/// The sublot number.
/// </value>

Maka saya akan mengatakan mereka memiliki nilai. Jadi untuk menjawab pertanyaan Anda: Komentar diperlukan ketika mereka mengatakan sesuatu yang tidak dikatakan oleh kode.

Pengecualian: sebaiknya ada komentar tentang apa pun yang dapat diakses publik jika Anda sedang menulis perpustakaan / API yang akan tersedia untuk umum. Saya benci menggunakan perpustakaan dan melihat fungsi bernama getAPCDGFSocket()tanpa penjelasan tentang apa itu APCDGFSocket (saya senang dengan sesuatu yang sederhana This gets the Async Process Coordinator Data Generator File Socket). Jadi dalam hal ini, saya akan mengatakan menggunakan beberapa alat untuk menghasilkan semua komentar dan kemudian secara manual mengubah yang membutuhkannya (dan tolong pastikan akronim samar Anda dijelaskan).

Selain itu, getter / setter umumnya adalah contoh buruk untuk "apakah komentar diperlukan?" karena biasanya cukup jelas dan komentar tidak diperlukan. Komentar lebih penting pada fungsi yang melakukan beberapa algoritma di mana beberapa penjelasan tentang mengapa hal-hal dilakukan dengan cara mereka dapat membuat kode lebih mudah dimengerti dan juga membuatnya lebih mudah bagi programmer masa depan untuk bekerja dengannya.

... dan akhirnya, saya cukup yakin bahwa pertanyaan ini relevan untuk semua gaya komentar, bukan hanya yang diformat menggunakan XML (yang Anda gunakan karena Anda bekerja di lingkungan .NET).

Komentar yang terlihat tidak berguna bagi pengguna yang dapat membaca kode menjadi lebih bermanfaat bagi pengguna yang tidak memiliki akses ke sumber. Ini terjadi ketika kelas digunakan sebagai API eksternal oleh orang-orang di luar organisasi Anda: HTML yang dihasilkan dari dokumen XML Anda adalah satu-satunya cara mereka untuk belajar tentang kelas Anda.

Yang mengatakan, komentar yang mengulangi nama metode dengan spasi tambahan antara kata-kata tetap tidak berguna. Jika kelas Anda akan digunakan di luar organisasi Anda, Anda perlu mendokumentasikan paling tidak rentang yang valid untuk nilai Anda. Misalnya, Anda harus mengatakan bahwa pengaturan UnitOfMeasureuntuk nulladalah ilegal, bahwa nilai dipasok ke setter tidak harus mengandung spasi di awal atau di akhir string, dan sebagainya. Anda juga harus mendokumentasikan kisaran LabelSerialNumberjika berbeda dari dataran Int32: mungkin tidak mengizinkan angka negatif ^*, atau tidak mengizinkan lebih dari tujuh digit. Pengguna internal Anda mungkin menerima begitu saja, karena mereka melihat nomor seri hari demi hari, tetapi pengguna eksternal mungkin benar-benar terkejut melihat pengecualian dari apa yang tampak seperti setter yang tidak bersalah.

Anda benar tentang menghindari komentar tidak berguna tersebut. Mereka membuat membaca kode lebih sulit daripada membuatnya lebih mudah, dan mengambil terlalu banyak ruang.

Dalam praktik saya, orang-orang yang menulis komentar dengan getter / setter, cenderung menghilangkan komentar ketika itu benar-benar diperlukan (seperti membangun kueri-sql 20-baris untuk komponen tanpa dokumentasi).

Saya menulis komentar ketika ada beberapa solusi jelas lainnya _ Saya menunjukkan mengapa pendekatan ini telah digunakan. Atau ketika sulit untuk mendapatkan ide tanpa mengetahui semua detailnya _ Saya mendaftar secara singkat detail yang diperlukan untuk memahami kode.

Contoh yang Anda bawa adalah lebih banyak menulis komentar untuk mengatakan bahwa seseorang menulis komentar daripada membuat hidup orang lain (dan mereka juga) lebih mudah.

BTW Anda dapat meningkatkan kemampuan Anda menulis komentar dengan kembali ke kode lama Anda dan mencoba memahaminya (Anda mungkin bahkan tidak mengenali kode Anda sendiri dalam 2-3 bulan _ ini benar-benar seperti membaca kode orang lain). Jika Anda melakukan ini tanpa rasa sakit, dari semuanya baik-baik saja.