Co powinienem zawrzeć w komentarzach do dokumentacji XML?

13

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?

mbmcavoy
źródło
6
„i idealnie będzie miał 100% zasięgu” - To bardzo dyskusyjne. Lubię je za publiczny interfejs typu wyłącznie do wyskakujących okienek inteligentnych, ale w przypadku metod prywatnych są po prostu zbyt gadatliwi IMO
Ed S.,
3
100% pokrycia nie dotyczy metod prywatnych, szczególnie obsługi zdarzeń.
SLaks,
1
GhostDoc pisze dla mnie moją dokumentację. „Co robi GetData()”, pytasz? Cóż, Gets the dataoczywiście!
Devin Burke,
2
@Justin: GhostDoc wygląda całkiem fajnie. Mogę to podnieść.
1
@Justin: arg, nienawidzę GhostDoc - początkowo wydaje się być genialny, ale po chwili zdajesz sobie sprawę, że możesz dostrzec automatycznie generowane komentarze o milę, zwykle gdy wracasz stary kod i musisz dowiedzieć się, co on robi. Chociaż sprawia, że ​​bardzo łatwo jest komentować wszystko XML, nie zapewnia, że ​​te komentarze zawierają jakiekolwiek rzeczywiste informacje. GhostDoc daje dobry punkt wyjścia, ale bardzo łatwo jest być leniwym i pominąć wszystko, czego nie mogłeś zrozumieć, zerkając na imię i podpis.
Keith

Odpowiedzi:

10

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.

SLaks
źródło
6

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ź)

codeConcussion
źródło
Domyślam się, że this.sprawa mogła się rozpocząć, ponieważ z jakiegoś powodu oficjalne wytyczne Microsoft zaleciły stosowanie dokładnie tej samej konwencji nazewnictwa dla zmiennych lokalnych i privatezmiennych instancji . Jest to strasznie wadliwy styl, IMO - w niektórych przypadkach jesteś jednym grubym palcem od StackOverflowExceptionnieruchomości setlub MyProperty = MyProperty;powodujesz, że pole jest inicjowane na zero zamiast parametru konstruktora, a nawet Microsoft kontynuował używanie m_wewnętrzne przez większość czasu .
jrh
2

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.

Keith
źródło
Zależy. Co zrobić, jeśli masz public getale internal setjako własność? Jak to komentujesz? :-)
Guillaume,
1
@Guillaume, ponieważ komentarze XML są publiczne, po prostu udokumentuję getXML i udokumentuję go setzwykłymi //komentarzami.
Keith,