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

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ę.

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

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!

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

    }

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.

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ć.

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ć.

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ą.

„ 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).

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ą.

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ół).

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