Bir yöntem yorumu genellikle çok benzer olduklarında hem özet hem de dönüş açıklaması içermeli midir?

Ben düzgün belgelenmiş kodun bir savunucusuyum ve bunun olası dezavantajlarının farkındayım . Bu, bu sorunun kapsamı dışındadır.

Visual Studio'da IntelliSense'i ne kadar sevdiğimi göz önünde bulundurarak herkese açık XML üyeleri ekleme kuralını izlemeyi seviyorum.

Ancak benim gibi aşırı bir yorumcunun bile rahatsız ettiği bir fazlalık biçimi vardır. Örnek olarak List.Exists () yöntemini ele alalım .

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summaryve returnstemelde aynı şeyi söylüyorlar. Sıklıkla, özeti daha çok bir returnsperspektiften yazarak , returnsbelgeleri tamamen bırakıyorum .

Liste belirtilen yüklem tarafından tanımlanan koşullarla eşleşen öğeler içerdiğinde true değerini, aksi takdirde false değerini döndürür.

Ayrıca, iade belgeleri IntelliSense'te görünmüyor, bu yüzden hemen ilgili bilgileri yazıyorum summary.

1. Neden returnsayrı olarak dokümantasyon yapmanız gerekiyor summary?
2. Microsoft'un bu standardı neden benimsediğine dair herhangi bir bilgi var mı?

Birini diğerinden çıkarabilirsiniz, ancak bu iki bölüm ayrı kalır, çünkü kodu incelerken / kullanırken kişiyi ilgilendiren bölüme odaklanmaya yardımcı olur .

Örneğinizi alarak, şunu yazmayı tercih ederim:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• Bu kodu gözden geçiriyorsanız ve yöntemin ne yaptığını bilmek istiyorsanız, özeti okudum ve önemsediğim şey bu.

• Şimdi, yönteminizi kullandığımı ve girdiğimde aldığım dönüş değerinin garip olduğunu düşünelim. Şimdi, yöntemin ne yaptığını gerçekten bilmek istemiyorum, ancak dönüş değeri hakkında daha fazla şey bilmek istiyorum. Burada <returns/>bölüm yardımcı oluyor ve özeti okumama gerek yok.

Yine bu örnekte, özeti özetleyebilir ve özetten <returns/>beklenen dönüş değerini çıkarabilirsiniz. Ama aşırı aynı tartışmayı alarak tüm adresinden yöntemi belgelemek için gerek yoktur yöntemin adı, içine koymak: Bu durumda List<T>olan, Predicate<T> matchbir tek argüman kendisi oldukça açık olduğu gibi.

Unutmayın, kaynak kodu bir kez yazılır, ancak birçok kez okunur . Kodunuzun diğer okuyucuları için tüketim miktarını azaltabilir, XML belgelerinde ek bir cümle yazarken on saniye harcarsanız bunu yapın.

Kullanımım: yöntemin ne yaptığını
<summary> açıklar (almak için ). Dönüş değerini açıklar .<returns>
<returns>

MSDN Bağlantılar: <summary>.<returns>

İadeleri neden özetten ayrı olarak belgelemeniz gerekiyor?

Özet bölüm gerçekten uzun ve açıklayıcı ise, sonunda ayrı, kısa bir dönüş parçası olması yararlı olabilir.

Genellikle <summary>kendi kodumdaki kısmı yazıyorum , "İade _ " dediğiniz şekilde ifade ediyorum .

Bir arayanın yöntem adından ve parametrelerinden (ve adlarından) açık olmadığını bilmesi gereken herhangi bir açıklamada bulundum. Umarım, yöntem adı ve parametreleri yorumun çok kısa olabileceğini açıkça ortaya koyar.

Son zamanlarda aynı felsefi sorudan ayrıldım ve hala iyi bir çözümün ne olduğundan emin değilim. Ama şimdiye kadar bu benim yaklaşımımdı ...

• Yöntem dokümantasyonu yalnızca harici arayanların bilmesi gerekenleri açıklar. Bu çalışmanın dahili olarak nasıl yapıldığı hakkında konuşmaz, ancak a) arayanın neden bu yöntemi çağırmak isteyeceğini, b) yöntemi çağırmanın beklenen sonuçlarının ne olacağını belirtir. Yöntemin nasıl çalıştığını belgelemeye ihtiyaç varsa, bunu kod gövdesinin içine koydum.
• Bir yöntemin yeterli karmaşıklığı varsa, genel açıklama ve ayrı bir [döndürme] bölümü haklı görünmektedir. Okuyucunun tüm açıklamayı okumasını ve dönüş değerinin nasıl yorumlanacağını çıkarmaya çalışmasını istemezsiniz.
• Yöntem ne kadar basit olduğunu açıklamak için en iyi yolu "Bu yöntem kişinin adresini döndürür" gibi bir şey söylemek, o zaman ekleme eklemek DRY ilkesine aykırı gibi görünüyor gibi [döner] bölümünü atlamak bunun büyük bir savunucusu. Birçok tek katmanlı erişimci yöntemi bu kategoriye giriyor gibi görünüyor.

Özet, faydalı olabileceği kadar açıklayıcı olmalıdır; parametrelerin açıklamaları ve dönüş değeri kısa ve tatlı olmalıdır. Bir kelime ile beş arasında bir seçiminiz varsa, bir kelime kullanın. Örneğinizi sıkılaştıralım:

Liste, belirtilen yüklem tarafından tanımlanan koşullarla eşleşen bir veya daha fazla öğe içeriyorsa true; aksi takdirde yanlış.

olur

List öğelerinden herhangi biri yüklemle eşleşirse true; aksi halde yanlış.