XML Yorumları Gerekli Belgeler midir?

Dokümantasyon için XML yorumları gerektiren bir hayranıydım. O zamandan beri iki ana nedenden dolayı fikrimi değiştirdim:

1. İyi kod gibi, yöntemler de kendinden açıklamalı olmalıdır.
2. Uygulamada, çoğu XML yorumu ek değer sağlamayan yararsız gürültüdür.

Çoğu zaman genel yorumlar oluşturmak için GhostDoc'u kullanırız ve işe yaramaz gürültü ile kastediyorum:

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

Bana göre bu çok açık. Bununla birlikte, dahil edilecek özel talimatlar varsa, kesinlikle XML yorumlarını kullanmalıyız.

Bu makaleden alıntıyı beğendim :

Bazen yorum yazmanız gerekebilir. Ancak, kural değil istisna olmalıdır. Yorumlar yalnızca kodla ifade edilemeyen bir şey ifade ettiklerinde kullanılmalıdır. Zarif bir kod yazmak istiyorsanız, yorumları ortadan kaldırmaya çalışın ve bunun yerine kendi kendini belgeleyen kod yazın.

XML yorumlarını yalnızca kod kendi başına açıklamak için yeterli olmadığında kullanmamız gerektiğini düşünmek yanlış mıyım?

Bu XML yorumların güzel kod çirkin görünmesi için iyi bir örnek olduğuna inanıyorum. Böyle bir sınıf alır ...

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

... Ve bunu buna dönüştürüyor:

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

Yorumlarınız sadece şu şekilde görünüyorsa:

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

O zaman evet, hepsi bu kadar kullanışlı değil. Eğer böyle bir şey okurlarsa:

/// <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>

Sonra onların değeri olduğunu söyleyebilirim. Sorunuzu cevaplamak için: Yorumlar, kodun söylemediği bir şey söylediklerinde gereklidir.

Bir istisna: herkese açık olacak bir kütüphane / API yazıyorsanız , herkesin erişebileceği herhangi bir şey hakkında yorum yapmak iyidir . Ben nefret adında bir işlev, bir kütüphaneyi kullanan ve görme getAPCDGFSocket()bir APCDGFSocket ne olduğu hiçbir açıklama ile (Ben basit olarak bir şey ile mutlu olurum This gets the Async Process Coordinator Data Generator File Socket). Bu durumda, tüm yorumları oluşturmak için bazı araçlar kullanın ve sonra ihtiyaç duyulanları manuel olarak ayarlayın (ve şifreli kısaltmalarınızın açıklandığından emin olun).

Ayrıca, alıcılar / ayarlayıcılar "yorumlar gerekli mi?" çünkü genellikle oldukça açıktır ve yorum yapmak gerekli değildir. Yorumlar, bazı şeylerin neden böyle yapıldığına dair bazı açıklamaların , kodu çok daha anlaşılır hale getirebileceği ve gelecekteki programcıların birlikte çalışmasını kolaylaştırabileceği bazı algoritma gerçekleştiren işlevler için daha önemlidir .

... ve son olarak, bu sorunun yalnızca XML kullanılarak biçimlendirilmiş olanlarla (.NET ortamında çalıştığınız için kullandığınız) değil, tüm yorum stilleri için geçerli olduğundan eminim .

Kodu okuyabilen kullanıcılara yararsız görünen yorumlar, kaynağa erişimi olmayan kullanıcılar için oldukça yararlı hale gelir. Bu, sınıf kuruluşunuz dışındaki kişiler tarafından harici bir API olarak kullanıldığında gerçekleşir: XML dokümanlarınızdan oluşturulan HTML'ler, sınıflarınız hakkında bilgi edinmenin tek yoludur.

Bununla birlikte, sözcükler arasına boşluk eklenmiş yöntem adını yineleyen bir yorum işe yaramaz. Sınıfınız kuruluşunuz dışında kullanılacaksa, değerleriniz için geçerli aralıkları belgelemeniz gerekir. Örneğin, bu ayarı demeliyim UnitOfMeasureiçin nullyasa dışıdır setter verilen değer başında veya dize sonundaki boşluk içeren ve benzeri gerektiğini. Ayrıca LabelSerialNumber, bir ovanınkinden farklıysa , aralığını da belgelemeniz gerekir Int32: belki de negatif sayılara izin vermez ^*, veya yedi basamaktan fazlasına izin vermez. Dahili kullanıcılarınız bunu kabul etmek için alabilirler, çünkü seri numaralarına her gün bakarlar, ancak dış kullanıcılar masum bir ayarlayıcıya benzeyen bir istisna görmekten gerçekten şaşırabilirler.

Bu tür gereksiz yorumlardan kaçınmak konusunda kesinlikle haklısınız. Kodu kolaylaştırmak yerine kodu okumayı zorlaştırıyor ve çok fazla yer kaplıyorlar.

Uygulamamda, alıcılar / ayarlayıcılarla yorum yazan kişiler, gerçekten gerekli olduğunda yorumları ihmal etme eğilimindedir (dokümantasyonu olmayan bir bileşen için 20 satırlık bir sql sorgusu oluşturmak gibi).

Başka bariz çözümler olduğunda yorum yazıyorum _ Tam olarak bu yaklaşımın neden kullanıldığını belirtiyorum. Ya da tüm detayları bilmeden fikir edinmek zor olduğunda _ Kodu anlamak için gerekli detayları kısaca listeliyorum.

Getirdiğiniz örnek, başkalarının (ve onların da) hayatını kolaylaştırmak yerine yorum yazdığını söylemek için yorum yazmaktır.

BTW, eski kodunuza dönerek ve anlamaya çalışarak yorum yazma yeteneğinizi artırabilirsiniz (2-3 ay içinde kendi kodunuzu bile tanımayabilirsiniz _ bu kesinlikle başkasının kodunu okumak gibi). Bunu acısız bir şekilde yaparsanız, her şey yolunda değil.