XML dokümantasyon yorumlarına neler eklemeliyim?

Özellikle sınıf üyeleri üzerinde XML yorum geldiğinde, kodumu daha iyi belgelemek için bir nokta yapmaya çalışıyorum, ama çoğu zaman sadece saçma geliyor.

Olay işleyicileri söz konusu olduğunda, adlandırma kuralı ve parametreleri standart ve açıktır:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

Ayrıca sık sık özeti (böylece) açıkça adlandırılan (IMO) basit özelliklere sahip:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

Bu tür yorumların, bildirimin kendisinin zaten sunmadığı herhangi bir bilgi eklemediğini düşünmüyorum. Genel bilgelik, kodu tekrarlayan bir yorumun en iyi şekilde yazılı olmadığı gibi görünmektedir.

Açıkçası, XML dokümantasyon normal sıralı kod yorumlarından daha fazlasıdır ve ideal olarak% 100 kapsama alanı olacaktır. Ne olmalıdır Böyle durumlarda yazılı olması? Bu örnekler uygunsa, şimdi takdir etmeyeceğim değeri katıyorlar mı?

c# coding-style

— mbmcavoy
kaynak

"ve ideal olarak% 100 kapsama alanı olacak" - Bu çok tartışmalı. Onları bir türün genel arayüzü için sadece intellisense pop-up'ları için seviyorum, ancak özel yöntemler için sadece çok ayrıntılı IMO

— Ed S.

% 100 kapsam, özel yöntemler, özellikle olay işleyicileri için geçerli değildir.

— SLaks

GhostDoc belgelerimi benim için yazıyor. "Ne yapar GetData()?" Neden, Gets the datatabii ki!

— Devin Burke

@ Justin: GhostDoc oldukça havalı görünüyor. Onu alabilirim.

@Justin: arg, GhostDoc'dan nefret ediyorum - ilk başta parlak görünüyor, ancak bir süre sonra otomatik olarak oluşturulan yorumları bir mil uzakta, genellikle eski kodu geri döndüğünüzde ve ne yaptığını anlamanız gerektiğinde fark edersiniz. Her şeyi XML olarak yorumlamayı çok kolay hale getirse de , bu yorumların içinde gerçek bir bilgi olmasını sağlamaz . GhostDoc size iyi bir başlangıç noktası verir, ancak tembel olmanızı ve isme ve imzayı görerek anlayamayacağınız her şeyi bırakmanızı çok kolaylaştırır.

— Keith

Yanıtlar:

XML doc yorumları herkese açıktır.

Uyarı derleyici bunu açıkça belirtmektedir:

Herkese görünür tür veya üye 'Type_or_Member' için XML yorumu eksik

Özel üyelere XML yorumları eklemeniz gerekir, ancak bu üyelerin isimleri zaten belli değilse.

— SLaks
kaynak

Saf görüş burada, bu yüzden buna değer için al.

Ben nefret gereksiz xml yorumlar. Şüphesiz, yöntem / özellik adına boşluk ekleyen hayalet doktor tarzı olanlar için. Hiçbir değer katmaz ve sadece gerçek kod hakkındaki görüşümü keser.

Bir şeyin açıklığa ihtiyacı varsa, elbette, yorum yapın. Bununla birlikte, anlamlı adlara sahip küçük odaklı yöntemlerle çok açıklık iletilebilir. Eğer kodu geliştirebilir ve yorumu gereksiz kılabilirseniz yorum yazmayın.

Hatta bana gereksiz kullanımına başlamak etmeyin this.ve Me..

Bir yan not olarak, xml yorumlarının görünürlüğünü değiştirmeme izin veren bir Visual Studio eklentisine sahip olmak isterim. (ipucu ipucu)

— codeConcussion
kaynak

this.Bazı nedenlerden dolayı Microsoft'un resmi yönergeleri yerel değişkenler ve örnek privatedeğişkenler için tam olarak aynı adlandırma kuralının kullanılmasını önerdiğinden , bu şeyin başlamış olabileceğini tahmin ediyorum . Bu çok kusurlu bir stil, IMO - bazı durumlarda bir StackOverflowExceptionmülkün içinde bir şişman parmaksınız setya da MyProperty = MyProperty;bir yapıcı parametresi yerine bir alanın sıfıra başlatılmasına neden oluyorsunuz ve Microsoft bile m_çoğu zaman dahili olarak kullanmaya devam ediyor .

— jrh

Herkese açık bir üye için XML belgeleri @SLaks'ın belirttiği gibi oldukça ayrıntılı ve eksiksiz olmalıdır.

Ancak özel, korunan veya dahili üyeler için de gerçekten yararlı olabilirler, çünkü Visual Studio intellisense yerleştirecek ve araç ipuçlarını XML doc yorumlarıyla yardımcı olacaktır.

Bunun anlamı şudur ki:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

Tamamen yeterli dokümantasyon olabilir, ancak:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

Kodunuzun herhangi bir yerinden hızlı bir şekilde görmek çok daha kolay olacaktır.

Genel olarak herkese açık XML yorumlarında API'nın bazı harici kullanıcıları için yazıyorum ve dahili XML yorumlarında benim veya ekibim için başkaları için yazıyorum.

Parametre açıklamalarını atlamak muhtemelen birincisi için kötü ve ikincisi için iyi bir fikirdir.

(Özellikle genel API belgelerinde) her zaman özellikleri getveya özellikleri ekleyebilirim set:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

Bu ister C # 'ın intellisense gelen belli değil getya setmevcuttur, ancak XML açıklaması üzerine koyarak size Araç ipucundan bir bakışta söyleyebilir anlamına gelecektir.

— Keith
kaynak

Bağlı olmak. Bir mülk olarak bir public getama bir varsa internal set? Nasıl yorumluyorsunuz? :-)

— Guillaume

@Guillaume XML yorumları kamuya açık olduğundan sadece getXML ile belgelemek ve setdüzenli //yorumlarla belgelemek istiyorum .

— Keith