Dlaczego bloki komentarzy /// są ważne?

49

Ktoś kiedyś powiedział, że powinniśmy poprzedzić wszystkie nasze metody /// <summary>blokami komentarzy (C #), ale nie wyjaśnił dlaczego.

Zacząłem ich używać i zauważyłem, że trochę mnie denerwują, więc przestałem ich używać, z wyjątkiem bibliotek i metod statycznych. Są nieporęczne i zawsze zapominam o ich aktualizacji.

Czy jest jakiś dobry powód, aby używać /// <summary>bloków komentarzy w kodzie?

Zwykle używam //komentarzy cały czas, to tylko /// <summary>bloki, o których zastanawiałem się.

Rachel
źródło
1
Nie byłem pewien, czy te bloki komentarzy są osobistymi preferencjami, czy zalecanymi standardami
Rachel
1
Myślę też, że SO.
Ryan Hayes,
30
Myślę, że właśnie takie pytanie należy tutaj. Istnieje duża szansa, że ​​zostanie to zamknięte przy przepełnieniu stosu jako subiektywne.
Paddyslacker,
Użyj bloków <podsumowanie>, jeśli chcesz wygenerować dokumentację. Ma to sens, jeśli tworzysz interfejs API dla innych. Robienie tego dla każdej metody jest nadmierne i zmniejsza twoją elastyczność.
Macneil

Odpowiedzi:

91

Używaj ich jak najwięcej.

Tak, są to specjalne komentarze, które stają się dokumentacją metody. Zawartość <summary>, generowane tagi parametrów itp. Pojawiają się w intellisense, gdy ty lub ktoś inny przygotowujesz się do wywołania twojej metody. Mogą zasadniczo zobaczyć całą dokumentację dla twojej metody lub klasy bez konieczności przechodzenia do samego pliku, aby dowiedzieć się, co on robi (lub spróbuj po prostu przeczytać podpis metody i mieć nadzieję na najlepsze).

Ryan Hayes
źródło
22
+1 Absolutnie ich używaj. Byłbyś zaskoczony, jak przydatne jest ich posiadanie, jeśli kiedykolwiek użyjesz ponownie swoich komponentów i będziesz mieć dostęp do całej tej wspaniałej dokumentacji w intellisense.
Walter
4
Również jeśli używasz Visual Studio i zaczynasz wiersz z /// tuż przed deklaracją klasy, metody lub pola, VS wygeneruje dla ciebie strukturę dokumentacji XML - musisz tylko ją wypełnić. Zgadzam się, że to zajmuje dużo miejsca na ekranie, ale powiedziałbym, że to godny kompromis. Ponadto F # ma lepszą obsługę (np. Nie musisz używać <summary> i </summary>, ponieważ są „zakładane”).
ShdNx,
7
Ponieważ ta odpowiedź jest już najlepszym wyborem, po prostu dodam swój komentarz: kiedy dowiedziałem się, że podsumowanie jest wykorzystywane do inteligencji, a moje projekty wzrosły do ​​obecnego rozmiaru, bardzo się cieszę, że znalazłem tę funkcję. Zapamiętywanie, do czego służą moje metody i klasy, stało się ogromnym wyzwaniem, a dokumentowanie kodu za pomocą tego mechanizmu znacznie uprościło rzeczy, pozwalając mi skupić się na nowym kodzie i możliwości ponownego użycia zamiast próbować pamiętać, co zrobiono kilka miesięcy temu.
JYelton,
3
Wystarczy dodać jedną rzecz: te komentarze nie są wkompilowane w bibliotekę DLL, musisz dostarczyć powiązany plik XML z biblioteką DLL.
Benjol,
Są przydatne, ale sprawiają, że obecna klasa jest bardzo nieczytelna. Chciałbym mieć inny sposób, który nie zaśmieca kodu.
Jeroen van Langen
16

Tak, absolutnie używaj ich do wszystkiego, co chcesz zachować lub może być udostępnione.

Używaj ich także w połączeniu z Sandcastle i Sandcastle Help File Builder , który pobiera dane wyjściowe XML i zamienia je w piękną dokumentację w stylu MSDN.

W ostatnim miejscu, w którym pracowałem, co noc przebudowywaliśmy dokumentację i hostowaliśmy ją jako wewnętrzną stronę główną. Inicjały firmy były MF, więc MFDN;)

Zwykle po prostu tworzę plik .chm, który można łatwo udostępniać.

Zdziwiłbyś się, jak uzależniasz się od dokumentowania wszystkiego, gdy zobaczysz go w formacie MSDN!

Tom Morgan
źródło
1
Link do bloga wydaje się martwy (ostatni post 5 lat temu z uszkodzonym HTML na całej stronie), a lokalizacja projektu się zmieniła. Czy masz zaktualizowany link do Sandcastle?
12

Jeśli twój standard kodowania wymaga, abyś używał takich komentarzy (i może wymagać tego standard kodowania dla API lub frameworka), to nie masz wyboru, musisz użyć takich komentarzy.

W przeciwnym razie rozważ poważnie niestosowanie takich komentarzy. W większości przypadków można ich uniknąć, zmieniając kod w następujący sposób:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

do

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

do

    public bool IsAuthorizedToAccessResource( User user ) {

    }
azheglov
źródło
11
Chociaż zgadzam się, że kod powinien być samodokumentujący tak często, jak to możliwe, sugeruję stosowanie tego typu komentarzy, gdy tylko jest to możliwe (i częściej niż ogólne // komentarze). Komentarze /// XML zostały zaprojektowane do współpracy z IntelliSense, co może ułatwić tworzenie kolejnych miesięcy, gdy próbujesz wdrożyć utworzoną bibliotekę i nie pamiętasz, jak to działa.
Matt DiTrolio,
2
I myślę, że nie tylko z perspektywy Intellisense, ale także z perspektywy automatycznego generowania dokumentacji przydatne są komentarze xml. Ale tak jak w przypadku wszystkich komentarzy, wyczuwa to tylko to, że same komentarze są przydatne i dodają się do samodokumentowanego kodu.
Vaibhav,
5
Zgadzam się, że kiedy piszesz publiczne klasy API lub frameworka, standard kodowania powinien wymagać umieszczania komentarzy w kodzie, tak aby można było podłączyć IntelliSense i narzędzia dokumentacji. Ale to nie wszystko. Oprócz tej troski, podejście, które tutaj popieram, polega na tym, że gdy próbujesz uczynić kod czystszym i jaśniejszym, skup się na samym kodzie, a nie na komentarzu opisującym kod.
azheglov
3
@JYelton: twój komentarz błędnie przedstawia moją odpowiedź. Implikowałem bardziej opisowe nazwy, ale niekoniecznie dużo bardziej szczegółowe, z pewnością nie 60-znakowy identyfikator często nazywanej funkcji publicznej. Ponadto masz coś, co wydaje się być wysoce wyspecjalizowaną funkcją, ale wymaga bardzo ogólnego typu danych (XmlDocument) - to jeden zapach kodu. Następnie twój 60-znakowy identyfikator opisuje „jak”, a nie „co” - metody publicznej. To kolejny zapach. Główne przesłanie to: najpierw pomyśl o kodzie, a nie o komentarzu.
azheglov
2
@JYelton Problem z nazwą twojej metody nie polega na tym, że ma ona charakter opisowy, ale raczej opisuje co najmniej 2 oddzielne operacje i dlatego powinna zostać przekształcona w co najmniej 2 niezależne metody.
Neal
4

Nazwy klas, metod i właściwości powinny być oczywiste, więc jeśli ich potrzebujesz, prawdopodobnie będzie to zapach.

Jednak zalecałbym używanie ich na dowolnych publicznych klasach, metodach i właściwościach w interfejsie API, bibliotece itp. Przynajmniej wygenerują one dokumenty, aby pomóc każdemu programistowi korzystającemu z niego, i zapobiegną je napisać.

Ale w każdym razie go pokroisz, utrzymasz lub usuniesz.

John MacIntyre
źródło
11
Nazewnictwo to jedno, ale wymienianie ograniczeń parametrów lub potencjalnie zgłaszanych wyjątków jest nadal cenne.
Adam Lear
Tak, przyznaję, że masz rację, ale przez większość czasu ograniczenia parametrów są oczywiste, prawda?
John MacIntyre,
Nie jestem pewien, czy zgadzam się z Johnem. Przy tej logice żadna z metod .NET Framework nie powinna uzyskać żadnej pomocy Intellisense.
Vaibhav,
1
@vaibhav - Powiedziałem: „Poleciłbym używanie ich na dowolnych publicznych klasach, metodach i właściwościach w API, bibliotece itp.”…… to obejmowałoby to, o czym mówisz, prawda?
John MacIntyre
1
@John - dziwne, mogłem przysiąc, że przeczytałem coś zupełnie innego, kiedy napisałem ten komentarz. Ponieważ twój drugi akapit jest dokładnie tym, co powiedziałem w innym miejscu tego wątku. Więc muszę mieć kamienie w głowie, żeby napisać ten komentarz. Tak, zgadzam się z tym.
Vaibhav,
2

Jeśli okaże się, że musisz wracać i edytować komentarze, aby odpowiadały nowemu kodowi, być może robisz je źle w pierwszej kolejności. Element podsumowania powinien zawierać dokładnie to - podsumowanie - co i dlaczego tego, co podsumowujesz.

Opisanie, jak coś działa w komentarzach, narusza SUSZENIE. Jeśli twój kod nie jest wystarczająco opisowy, być może powinieneś wrócić i zreformować.

Nikt
źródło
1

Tak, stworzyłem je. [podczas budowania nowych systemów od zera]

Nie, nigdy z nich nie skorzystałem. [podczas pracy na istniejących systemach wymagających konserwacji]

Odkryłem, że komentarze „Podsumowanie” w końcu nie są zsynchronizowane z kodem. A kiedy zauważę kilka źle zachowujących się komentarzy, tracę wiarę we wszystkie komentarze na temat tego projektu - nigdy nie masz pewności, którym zaufać.

Preets
źródło
Stare komentarze można jednak uznać za zapach kodu, tym bardziej na poziomie podsumowania. Jeśli inni programiści zmieniają funkcje i nie aktualizują podsumowania swoich działań, można argumentować, że nie dokumentują poprawnie swojej pracy.
rjzii
1

Zapomnienie o zrobieniu czegoś nie jest złym pomysłem. Zapomniałem zaktualizować jakąkolwiek dokumentację. Uważam, że są one bardzo przydatne w moim programowaniu i ludzie, którzy dziedziczą mój kod, są wdzięczni za ich posiadanie.

Jest to jeden z najbardziej widocznych sposobów dokumentowania kodu.

Trudno jest znaleźć kod źródłowy, aby przeczytać dokumentację wbudowaną lub wykopać dokument, który przejdzie to, co robi kod. Jeśli dzięki inteligencji możesz wyskoczyć coś użytecznego, ludzie cię pokochają.

Abe Miessler
źródło
1

Musi być używany bardzo podobnie jak ja;)

Kiedyś bawiłem się komentarzami (///). W przypadku klasy możesz po prostu zrobić taki komentarz

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Ale w przypadku metody można dodać więcej, podając opis parametrów i typów zwracanych.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Do utworzenia tego komentarza możesz użyć skrótu (///+Tab).

Sreekumar P.
źródło
0

używając ich, z wyjątkiem bibliotek

To czas, kiedy są użyteczne. Po włączeniu generowania Dokumentacji XML i odwołania do zestawu, bez jego projektu, pokażą więcej szczegółów w intellisense.

Ale w przypadku elementów wewnętrznych obecnego projektu przeszkadzają.

Richard
źródło
0

Używam ich, ale jak niektórzy inni mówili nie powszechnie. W przypadku małych metod mogą z łatwością być większe niż kod, który wyjaśniają. Są one najbardziej przydatne do generowania dokumentacji, która może być przekazana osobom początkującym w systemie, aby mieli do czego się odwoływać podczas nauki. Chociaż jako programiści zwykle możemy odkryć, co to jest za kod, fajnie jest mieć komentarze, które prowadzą nas i działają jak kula. Jeśli to ma być zapisane gdzieś następnie w kodzie jest miejsce, jest bardzo prawdopodobne, aby być na bieżąco aktualizowana (bardziej prawdopodobne niż jakiegoś dokumentu Word pływających wokół).

Todd Williamson
źródło
0

Używam ekwiwalentu w VB (ponieważ nie pozwalają mi używać C # - najwyraźniej jest to zbyt trudne ... bez komentarza). Uważam, że są bardzo wygodne. Przez większość czasu czekam, aż procedura lub funkcja zostaną prawie ukończone, zanim je wstawię, choćby po to, aby uniknąć konieczności zmiany komentarzy - lub ich „niezsynchronizowania”.

Niekoniecznie piszę powieść - tylko podstawy, opis parametrów i kilka uwag (zwykle gdy dzieje się tam coś „niezwykłego” - obejście lub inne bzdury, których wolałbym nie mieć, ale mam nie ma wyboru „na razie”.) (Tak, wiem, że „na razie” może trwać lata).

Jestem mocno zirytowany niechcianym kodem. Konsultant napisał wstępną wersję jednego z naszych komponentów i nic nie skomentował, a jego wybór nazw pozostawia do życzenia tu i tam. Nie ma go ponad rok, a my wciąż zajmujemy się jego sprawami (oprócz pracy nad własnymi).

MetalMikester
źródło