Özelliklerin XML dokümantasyonunda “Alır veya ayarlar ..” gerekli midir?

C # XML yorumları için en iyi uygulama bir öneri arıyorum. Bir özellik oluşturduğunuzda, beklenen XML belgelerinin aşağıdaki formu olduğu görülüyor:

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

Ancak mülkün imzası zaten sınıfın dış istemcileri için hangi işlemlerin kullanılabilir olduğunu söylediğinden (bu durumda her ikisi de getve set) Yorumlar çok konuşkan ve belki de aşağıdakilerin yeterli olacağını hissediyorum:

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

Microsoft ilk formu kullanır, bu nedenle zımni bir kural gibi görünür. Ama ikincisinin belirttiğim nedenlerle daha iyi olduğunu düşünüyorum.

Bu sorgunun yapıcı olmadığı belirtilmek için bir usta olduğunu anlıyorum, ancak birisinin yorum yapması gereken özellik miktarı çok büyük ve bu sorunun burada olma hakkı olduğuna inanıyorum.

Resmi olarak önerilen uygulamalarla ilgili fikirleri veya bağlantıları takdir edeceğim.

İmza, diğer kod parçalarına hangi işlemlerin yapılabileceğini söyleyebilir; bununla birlikte, çalıştığı için kodlayıcıya açıkça gösterilmezler ve XML dokümantasyonu insanların bir derleyici değil tüketmesi içindir.

Örneğin bu sınıfı ele alalım:

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

Bu özelliklerden birine erişmek için istihbarat yükseltildiğinde, hangilerinin yazılabileceği, okunabileceği veya her ikisinin de yazılabileceğine dair bir gösterge yoktur:

Aynı şekilde, belgeleri görüntülerken de tam olarak emin değiliz:

Bu nedenle biz eklemek alır veya ayarlar , alır veya ayarlar kod yazarken programcı üzerinde kolaylaştırmak için. Kesinlikle bazı verileri okuyan ve işleyen büyük bir kod bloğu yazmak, yalnızca bu verileri beklendiği gibi tekrar mülke yazamayacağınızı öğrenmek için olmaz.

StyleCop, Gets or Sets ...kural SA1623 ile uyguladığı notasyonu kullanır .

Bağlantı verilen sayfada, listelemediğiniz başka bir vaka listelenir:

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

Listelediğiniz diğer seçenek olurdu.

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

Bu özellik sadece okunan Intellisense ipucu hakkında bilgi sağlamaz, bu dava için de bir kongre ile gelebilir, ama Gets ..., Gets or Sets...iş güzel imo yapar.

StyleCop kuralında listelenen, Gets or Sets...ancak kullanılarak açık olan ancak olmayan diğer değişkenler de vardır .

Ayrıca Doxygen veya Sandcastle gibi bir şeyden belge oluştururken, tam gösterim API'yi (örneğin) daha iyi belgeleyecektir.

XML yorumlarında bir özelliğin edinilmesi ve ayarlanması hakkında bilgi eklediğim tek zaman, beklendiği gibi davranmadığı zamandır (düz genel alma ve ayarlama).

Ya özel veya ek mantık içeriyorsa, o zaman ben söz, aksi takdirde ben sadece mülkiyet niyetini belge.

Daha ayrıntılı sürümle daha mutlu olurdum.

Diğeri, bir sayaç değişkenini artırdıktan sonra "artış sayacı" hakkında yorum yapmak gibidir.

Bir Get ve Set olduğu açıktır. Özel bir ayarlayıcınız olsaydı, özel anahtar kelimeye sahip olacağınız açıktır.

Yorumlar değer katmalı, sadece kodun gerçekte yorum versiyonu olmamalı.