Saya dulu penggemar yang membutuhkan komentar XML untuk dokumentasi. Sejak itu saya berubah pikiran karena dua alasan utama:
- Seperti kode yang baik, metode harus jelas.
- 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; }
}
2
Saya berpendapat XML adalah pilihan yang mengerikan untuk tujuan ini. Itu terlalu verbose dan umum untuk digunakan. Lihat reStructuredText dan sphinx untuk bahasa markup yang disematkan ke komentar tanpa membuatnya tidak dapat dibaca.
—
Latty
@ Lattyware: VisualStudio mendukung gaya ini secara default, tidak ada plugin atau alat tambahan yang diperlukan. Komentar yang dihasilkan dengan cara ini langsung terlihat di pop-up tooltips.
—
FrustratedWithFormsDesigner
@FrustratedWithFormsDesigner Saya akan mengatakan bahwa mendapatkan plugin sepadan untuk membuat kode Anda jauh lebih mudah dibaca. Dukungan bawaan untuk reST dengan tooltips seperti itu ada di PyCharm, jadi saya yakin plugin ada untuk bahasa lain di IDE lain. Jelas jika Anda memiliki proyek di mana semuanya didokumentasikan dengan cara ini, saya tidak menyarankan Anda mulai membagi cara itu dilakukan, tetapi untuk proyek-proyek baru, saya hanya berpikir itu sangat mengerikan untuk dibaca dan dipelihara.
—
Latty