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?
źródło
GetData()
”, pytasz? Cóż,Gets the data
oczywiście!Odpowiedzi:
Komentarze do dokumentu XML są przeznaczone dla członków publicznych.
Kompilator ostrzeżenie wyraźnie stwierdza w ten sposób:
Komentarze XML należy dodawać do prywatnych członków tylko wtedy, gdy nie są oni jeszcze wyraźnie związani z ich nazwami.
źródło
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.
iMe.
.Na marginesie chciałbym mieć dodatek Visual Studio, który pozwala mi przełączać widoczność komentarzy XML. (podpowiedź podpowiedź)
źródło
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 iprivate
zmiennych instancji . Jest to strasznie wadliwy styl, IMO - w niektórych przypadkach jesteś jednym grubym palcem odStackOverflowException
nieruchomościset
lubMyProperty = MyProperty;
powodujesz, że pole jest inicjowane na zero zamiast parametru konstruktora, a nawet Microsoft kontynuował używaniem_
wewnętrzne przez większość czasu .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:
Może to być całkowicie wystarczająca dokumentacja, ale:
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
get
lubset
na właściwości:To nie jest oczywiste z C # 's intellisense czy
get
czyset
są dostępne, ale wprowadzenie go w komentarzu XML oznaczać będzie można powiedzieć na pierwszy rzut oka z podpowiedzi.źródło
public get
aleinternal set
jako własność? Jak to komentujesz? :-)get
XML i udokumentuję goset
zwykłymi//
komentarzami.