it-swarm-eu.dev

Proč jsou důležité bloky / / / komentáře?

Někdo jednou řekl, že bychom měli prefixovat všechny naše metody pomocí /// <summary> blokovat komentáře (C #), ale nevysvětlil proč.

Začal jsem je používat a zjistil, že mě docela trochu otrávili, takže jsem je přestal používat kromě knihoven a statických metod. Jsou objemné a vždy jsem je zapomněl aktualizovat.

Existuje nějaký dobrý důvod k použití /// <summary> komentovat bloky v kódu?

Normálně používám // komentáře po celou dobu, je to jen /// <summary> bloků, o kterých jsem přemýšlel.

49
Rachel

Používejte je co nejvíce.

Ano, jedná se o speciální komentáře, které se stávají dokumentací k této metodě. Obsah <summary>, generované značky parametrů atd., které se generují, se objeví inteligentně, když se vy nebo někdo jiný připravuje na zavolání vaší metody. Mohou v zásadě vidět veškerou dokumentaci k vaší metodě nebo třídě, aniž by museli jít do samotného souboru, aby zjistili, co dělá (nebo se pokusili jen přečíst podpis metody a doufat v to nejlepší).

91
Ryan Hayes

Ano, absolutně je používejte pro vše, co si chcete ponechat nebo které by mohlo být sdíleno.

Také je použijte ve spojení s Sandcastle a Sandcastle Help File Builder , který převezme výstup XML a promění jej v nádhernou dokumentaci ve stylu MSDN.

Poslední místo, kde jsem pracoval, jsme každou noc přestavovali a hostovali ji jako interní domovskou stránku. Iniciály společnosti byly MF, takže to bylo MFDN;)

Normálně však vytvářím pouze soubor CHM, který se snadno sdílí.

Byli byste překvapeni, jak jste závislí na dokumentování všeho, jakmile to začnete vidět ve formátu MSDN!

17
Tom Morgan

Pokud váš kódovací standard vyžaduje, abyste tyto komentáře používali (a kódovací standard pro API nebo rámec to může vyžadovat), pak nemáte na výběr, musíte takové poznámky použít.

V opačném případě zvažte použití těchto komentářů vážně. Ve většině případů se jim můžete vyhnout změnou kódu takto:

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

    }

na

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

    }

na

    public bool IsAuthorizedToAccessResource( User user ) {

    }
12
azheglov

Název vaší třídy, metody a vlastnictví by měl být zřejmý, takže pokud je potřebujete, je to pravděpodobně zápach.

Doporučil bych je však použít na jakýchkoli veřejných třídách, metodách a vlastnostech v API, knihovně atd. Prinajmenším vygenerují dokumenty, aby pomohly jakémukoli devu s jeho použitím, a zabrání vám mít napsat je.

Ale stejně to nakrájíte na plátky, udržujete je nebo je odstraníte.

4
John MacIntyre

Pokud zjistíte, že se budete muset neustále vracet a upravovat své komentáře tak, aby odpovídaly novému kódu, možná byste je na prvním místě udělali špatně. Souhrnný prvek by měl obsahovat přesně to - shrnutí - co a proč věci, kterou sumarizujete.

Popis jak něco funguje v komentářích porušuje DRY. Pokud váš kód není dostatečně popisný, možná byste se měli vrátit a refactor.

2
Nobody

Ano, vytvořil jsem je. [při stavbě nových systémů od nuly]

Ne, nikdy jsem z nich neměl prospěch. [při práci na stávajících systémech, které vyžadovaly údržbu]

Zjistil jsem, že komentáře v souhrnu mají tendenci se synchronizovat s kódem. A jakmile si všimnu několika špatně se chujících komentářů, mám tendenci ztratit víru ve všechny komentáře k tomuto projektu - nikdy si nejste jisti, kterým z nich důvěřovat.

1
Preets

Zapomínání na něco neznamená, že je to špatný nápad. Zapomínáte aktualizovat veškerou dokumentaci. Považuji je za velmi užitečné v mém programování a lidé, kteří zdědí můj kód, jsou vděční za to, že je mají.

Je to jeden z nejviditelnějších způsobů, jak dokument zdokumentovat.

Je bolestí, když musíte najít zdrojový kód, abyste si mohli přečíst inline dokumentaci nebo vykopat dokument, který jde nad tím, co kód dělá. Pokud můžete mít něco užitečného vyskočit přes inteligenci pak lidé budou milovat vás.

1
Abe Miessler

"Musí se používat velmi podobně jako já;)"

Hrával jsem s komentáři (///). Pro třídu můžete jednoduše udělat takovýto komentář

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

Ale pro metodu můžete přidat více s uvedením popisu parametrů a typů návratu.

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

Pro vytvoření tohoto komentáře můžete použít zkratku (///+Tab).

1
Sreekumar P

Ekvivalent používám v VB (protože mi nedovolí používat C # - zjevně je to příliš těžké ... bez komentáře). Považuji je za velmi pohodlné. Většinu času počkám, až procedura nebo funkce je před dokončením do značné míry dokončena, i když jen proto, aby se nemusely měnit komentáře - nebo aby byly „mimo synchronizaci“.

Nemusím nutně psát román - jen základy, popis parametrů a některé poznámky (obvykle, když se tam děje něco „neobvyklého“ - řešení nebo jiné svinstvo, které bych tam raději neměl, ale měl žádná volba "prozatím".) (Ano, vím, že "prozatím" může trvat roky.)

Jsem silně podrážděný nekomentovaným kódem. Konzultant napsal počáteční verzi jedné z našich komponent a nic nekomentoval a jeho výběr jmen nechal být požadovaný zde a tam. Byl pryč přes rok a stále třídíme jeho věci (kromě práce na vlastních věcech).

0
MetalMikester

jejich použití s ​​výjimkou knihoven

To je čas, kdy jsou užitečné. Se zapnutou generací dokumentace XML a odkazem na shromáždění bez jeho projektu se v inteligentním zobrazení zobrazí více podrobností.

Ale pro interní strany současného projektu se prostě dostanou do cesty.

0
Richard

Používám je, ale jak někteří lidé říkali ne všeobecně. Pro malé metody mohou být snadno větší než kód, který vysvětlují. Jsou nejužitečnější pro generování dokumentace, která může být dána lidem novým v systému, aby měli co učit, když se ji učí. I když, jako programátoři, můžeme obvykle fretrovat, jaký je nějaký kód, je pěkné, že máme komentáře, které nás povedou a působí jako berle. Pokud bude , aby bylo někde zapsáno, pak je v kódu místo, kde je nejpravděpodobnější zůstat aktualizovaný (pravděpodobnější než nějaký dokument Word plovoucí kolem).

0
Todd Williamson