Co powinienem zawrzeć w komentarzach do dokumentacji XML?

Staram się usprawnić dokumentowanie mojego kodu, szczególnie jeśli chodzi o komentarze XML do członków klasy, ale często wydaje się to głupie.

W przypadku procedur obsługi zdarzeń konwencja nazewnictwa i parametry są standardowe i jasne:

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

Często też mam proste właściwości o wyraźnej nazwie (IMO), dzięki czemu podsumowanie jest zbędne:

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

Nie wydaje mi się, aby takie komentarze nie dodawały żadnych informacji, których sama deklaracja jeszcze nie przekazuje. Ogólna mądrość wydaje się polegać na tym, że komentarz, który powtarza kod, najlepiej pozostawić niepisany.

Oczywiście dokumentacja XML to coś więcej niż zwykłe wbudowane komentarze do kodu i idealnie obejmuje 100% zasięgu. Co powinienem pisać w takich przypadkach? Jeśli te przykłady są w porządku, jaką wartość dodają, których teraz nie doceniam?

Komentarze do dokumentu XML są przeznaczone dla członków publicznych.

Kompilator ostrzeżenie wyraźnie stwierdza w ten sposób:

Brak komentarza XML dla publicznie widocznego typu lub członka „Type_or_Member”

Komentarze XML należy dodawać do prywatnych członków tylko wtedy, gdy nie są oni jeszcze wyraźnie związani z ich nazwami.

Czysta opinia tutaj, więc weź to za to, co jest warte.

Ja nienawidzę zbędnych komentarzy XML. Podwójnie tak dla widmowych stylów doc, które po prostu dodają spacje do nazwy metody / właściwości. Nie dodaje żadnej wartości i po prostu zaśmieca mój widok na rzeczywisty kod.

Jeśli coś wymaga wyjaśnienia, należy to skomentować. Jednak dużą przejrzystość można przekazać za pomocą małych, skoncentrowanych metod o znaczących nazwach. Nie komentuj kodu, jeśli możesz go poprawić i uczynić komentarz niepotrzebnym.

Nawet nie zaczynaj mnie od niepotrzebnego używania this.i Me..

Na marginesie chciałbym mieć dodatek Visual Studio, który pozwala mi przełączać widoczność komentarzy XML. (podpowiedź podpowiedź)

Na publicznym członku dokumenty XML powinny być dość pełne i pełne, jak wspomniano w @SLaks.

Mogą być jednak bardzo przydatne na prywatnych, chronionych lub wewnętrznych członkach, ponieważ Visual Studio zapełni intellisense i pomoże podpowiedziom w komentarzach do dokumentu XML.

To znaczy że:

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

Może to być całkowicie wystarczająca dokumentacja, ale:

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

Będzie o wiele łatwiej zobaczyć szybko z dowolnego miejsca w kodzie.

Ogólnie na temat publicznych komentarzy XML piszę dla jakiegoś zewnętrznego użytkownika API oraz na wewnętrznych komentarzach XML piszę dla mnie lub innych członków mojego zespołu.

Pomijanie opisów parametrów jest prawdopodobnie złym pomysłem w przypadku pierwszego i w porządku w przypadku drugiego.

Dodam (w docs API publicznych zwłaszcza) zawsze to, czy getlub setna właściwości:

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

To nie jest oczywiste z C # 's intellisense czy getczy setsą dostępne, ale wprowadzenie go w komentarzu XML oznaczać będzie można powiedzieć na pierwszy rzut oka z podpowiedzi.