Dokumentování a nasazení .NET aplikací

Další volné pokračování seriálu o .NET se bude zabývat vytvářením dokumentace. Porovnáme si možnosti Visual Basic .NET a C# v této oblasti a ukážeme, jak velice jednoduše vytvářet dokumentaci ala MSDN. Nakonec si zdokumentujeme ukázkovou třídu a vytvoříme pro ni instalační program.
Dokumentace v .NET

Produktivita

Když se podíváme na dnešní způsob vývoje programovacích nástrojů, přijdeme na to, že většinu věcí už někdo naprogramoval. Nejvíce času strávíme hledáním různých komponent, algoritmů a prohledáváním dokumentace. Tento čas se dá bez nadsázky označit jako neproduktivní a cílem každého programátora je jej co nejvíce omezit.

Klíčem k efektivitě programování je přehledná struktura programů, logická architektura a v neposlední řadě kvalitní a přehlední dokumentace. Pokud firmy zavedou striktní pravidla v tomto směru, zvýší několikanásobně svoji produktivitu.

Co se týče návrhu tříd a architektury systémů, jedná se o problém natolik komplexní, že bychom si jej tady určitě nevysvětlili. Co ale ovlivnit můžeme je, jak bude dokumentace k našemu kódu vypadat a tím přispět k zpřehlednění kódu. Na příkladech chci dnes ukázat, jak můžeme pomocí Visual Studia .NET i jiných nástrojů dokumentovat náš kód na velice slušné úrovni. Pojďme se nejdříve podívat na možnosti jednotlivých jazyků v .NET Frameworku.

C# vs. Visual Basic .NET

Visual Basic .NET je velice podobný C#. To je moje zkušenost, kterou jsem získal počas konvertování různých kódů z jednoho jazyka do druhého. Když záležitost hodně zjednoduším, stačí psát místo Begin … End kombinaci {..} . Oba jazyky používají stejné třídy z knihovny .NET Frameworku a v podstatě stejné datové typy.

Co mě ale uhranulo na C# je možnost jednoduše vytvářet dokumentaci kódu. Ta je velice pokročilá, umožňuje doplnění Intellisense nápovědy ve Visual Studiu .NET vašimi komentáři. Dále umožňuje pomocí dalších nástrojů vytvářet jedním kliknutím téměř dokonalou dokumentaci, která má podobu navlas stejnou jako dokumentace MSDN na kterou jsou všichni vývojáři zvyklý. Představte si následující ukázku:

Klepněte pro větší obrázek

V třídě Matematika máme jednu funkci, která je dokumentována pomocí C# dokumentace. Při použití dané třídy ve Visual Studiu je daná dokumentace automaticky použita.

Na obrázku jsou vlastně 2 obrázky v jednom. Nejdříve při psaní jména třídy AutoComplete vypíše všechny použitelné členy včetně nápovědy (1).

Pokud si danou funkci vybereme, nabídne nám seznam parametrů s nápovědou u aktuálního parametru (2).

Visual Studio .NET dále umožňuje vytvářet souhrnnou dokumentaci v podobě HTML, nebo XML. Pokud nemáte k dispozici Visual Studio .NET, můžete přeložit C# kód pomocí řádkového překladače csc.exe, který je zdarma a je součástí .NET Frameworku. Pokud při překladu použijete přepínač /doc:<soubor> , vygeneruje vám do určeného souboru dokumentaci v podobě XML. Dále je možné na tento soubor aplikovat příslušné XSLT styly a tím můžete přetransformovat XML dokumentaci v podstatě do čehokoliv - nejpravděpodobnější asi bude HTML.

Vytváření dokumentace v C#

Pokud v C# použijeme před definicí třídy, rozhraní nebo členu specielní komentáře začínající "///", můžeme vkládat XML dokumentaci k danému objektu pomocí různých značek. Nejčastěji používané jsou následující:

<summary></summary> Označuje blok, který obsahuje souhrnný popis daného členu. Doporučuji maximální rozsah 2-5 vět. Tento popis je pak použit v AutoComplete při výběru členů dané třídy, nebo je ve výsledné dokumentaci zobrazen jako zkrácený popis.
<remarks></remarks> Tady vkládejte všechno, co se nevešlo do části <summary/>. Nezapomeňte připojit informace o podporovaných platformách (pokud jsou podporovány jenom některé), specielních požadavcích a nutných nastaveních. V dokumentaci bude část remarks zobrazena v podrobném výpisu daného členu.
<example></example> Na příkladech se to vždy pochopí nejlépe, připojte proto krátkou ukázku syntaxe.
<see cref="Matematika"/> Vloží odkaz na daný člen, jmenný prostor nebo třídu.
<seealso cref="Matematika"/> Přidá do seznamu seealso odkaz na objekt související s popisovaným objektem.
<param name="x">Popis parametru x"</param> Tato sekce popisuje parametr dané funkce. Použije se při Intellisense nápovědě ve Visual Studiu .NET.

Kompletní referenční příručku všech dokumentovacích značek naleznete na MSDN. A samozřejmě si ukážeme příklad:

Naprogramoval jsem třídu ConfirmButton, která implementuje rozšířené tlačítko. To se od standardního tlačítka Button (ze kterého dědí) liší tím, že se před odesláním formuláře zeptá uživatele, zda skutečně chce odeslání provést:

/// <summary>
    /// ConfirmButton extends the functionality of System.Web.UI.WebControls.Button class in providing client-side confirmation
    /// using javascript:confirm before doing PostBack. Customize the text of question beign asked using the property <see cref="ConfirmMessage"/>.
    /// </summary>
    /// <example>
    /// ConfirmButton1.ConfirmMessage="Are you sure?";
    /// </example>
    /// <remarks>If client browser doesn`t support Javascript, the PostBack is generated without displaying the message.</remarks>

public class ConfirmButton:Button
{
/// <summary>
/// Question you want to ask before doing PostBack. If user clicks OK, PostBack is generated, otherwise nothing is done.
/// </summary>
  public string ConfirmMessage  = "Are you sure ?";

/// <summary>
/// This function adds the JavaScript behaviour to base Button class
/// </summary>
override protected void AddAttributesToRender(HtmlTextWriter writer)
{
writer.AddAttribute("onclick","return confirm(`"+ConfirmMessage +"`);");
base.AddAttributesToRender(writer);
}
}

A výsledná dokumentace po příslušných transformacích bude vypadat:

Klepněte pro větší obrázek

XML dokumentace může obsahovat jakékoliv další značky (musí ale odpovídat XML formátu). Ty se dají použít pro rozšíření funkčnosti, například o vkládání obrázků, atd.

Nástroje pro generování dokumentace

Jak jsem už ukázal v první kapitole, samotnou XML dokumentaci můžeme získat přímo z kompilátoru C#. Poté bychom měli výsledek prohnat XSLT transformací, abychom dostali požadovaný HTML formát, jaký obsahovala například předchozí ukázka.

Pokud nemáte čas, nebo chuť vytvářet si potřebné XSLT stylesheety, můžu vám nabídnout 2 programy, které vám s generováním HTML pomůžou. První je samotné Visual Studio .NET, které v menu Tools skrývá volbu Build Comment Pages. Tato funkce vytvoří HTML dokumentaci k vašemu projektu. Jak taková dokumentace vypadá pro již zmíněnou třídu ConfirmButton, se můžete podívat.

Osobně se mi dokumentace generována Visual Studiem moc nelíbila, protože nezobrazuje některé značky, ku příkladu <example/>.

Druhý, mnohem pokročilejší a navíc Open Source (licence GNU) nástroj je NDoc. Právě pomocí něj jsem vygeneroval dokumentaci v předchozí kapitole.

Klepněte pro větší obrázek

Nástroj umožňuje načíst soubor řešení (Solution File) Visual Studia .NET, nebo jenom konkrétní knihovnu. Nezapomeňte, že ta musí být přeložena pomocí přepínače /doc aby byl přístupný XML soubor s dokumentací. Na základě tohoto XML souboru a samotné knihovny vytvoří NDoc dokumentaci velice podobnou té z MSDN. Ukázku si můžete stáhnout.

Poznámka: Pokud váš projekt vytváříte pod Visual Studiem .NET, musíte nastavit generování XML souboru s dokumentací. Toto nastavení naleznete v okně Solution Explorer, po kliknutí na vlastnosti (Properties) daného projektu. Nastavte možnost Configuration Propertiest / Build / XML Documentation File na adresář do kterého chcete generovat XML dokumentaci (např. bin/).

Nasazení aplikace

Poté co jsem přepsal do C# a zdokumentoval Anketu z minulých dílů, je už připravena na používání. Teď se tedy nacházíme v situaci, kdy je projekt hotový, zdokumentovaný a připravený na dodání "zákazníkovi". Je načase ukázat si, jak projekt zabalíme do přehledného instalačního programu a zajistíme, že se všechny soubory dostanou tam, kam mají.

Pro tento účel použijeme Web Setup Projekt ve Visual Studiu. Ten nám umožňí nainstalovat naši komponentu ankety spolu s ukázkou na www server zákazníka a v případě odinstalace zajistí kompletní odstranění všech souborů:

Klepněte pro větší obrázek

Po otevření okna s projektem vidíme adresářovou strukturu výsledné aplikace (File System) přidáme požadované soubory. Já jsem vytvořil 2 adresáře:

  • První (přednastavený) obsahuje anketu (PollControl.ascx) a ukázku (PollExamples.aspx) plus další potřebné soubory. Tento adresář je typu WebFolder, co znamená, že bude nainstalován jako virtuální adresář IIS.
  • Druhý adresář jsem vytvořil kvůli tomu, že chci zpřístupnit celý zdrojový kód aplikace včetně instalačního projektu. Typ adresáře je Program Files Folder - název leccos naznačí :-).
Dále si otevřeme okno User Interface, který obsahuje definice dialogových oken seřazených podle toho, jak jdou za sebou v průběhu instalace. Po označení můžeme upravovat texty a obrázky jednotlivých dialogů v sekci Properties.

Můžeme přidávat další dialogy, např. já jsem přidal Readme dialog, ve kterém zobrazím soubor readme.rtf obsahující důležité informace pro uživatele.

Po zkompilování je vytvořena sada souborů které už můžeme distribuovat. Upozorňuji, že před instalací se musí na cílový počítač nainstalovat .NET Framework. Pokud byste chtěli vytvořit instalační program, který nejdříve nainstaluje potřebný Framework a až poté spustí samotnou instalaci, doporučuji tento článek.

Závěr

Myslím, že C# se jednoznačně před Visual Basic .NET staví svojí schopností dokumentace kódu. Pokud vytváříte aplikace sám pro sebe, není rozdíl v produktivitě až tak markantní. Ve větších projektech, kde je nutný určitý standard komunikace mezi členy týmu, je dobrý dokumentovací systém nutností. Intellisense v kombinaci s Autocomplete je podle mě velice silný doplněk a při správném komentování kódu umožní lepší orientaci v projektech vytvořených v C#.

Můj osobní názor je, že dokud Microsoft, nebo třetí strany také neuvedou podobné dokumentovací řešení pro Visual Basic .NET, vyplatí se kvůli těmto funkcím programovat ve C#.

Diskuze (5) Další článek: Konec nadvlády nVidii a ATi, přichází SiS Xabre

Témata článku: Software, Microsoft, Programování, Open source, Potřebný nástroj, Dok, Podobný objekt, Druhá sekce, Podobný nástroj, APL, Basic, Visual Basic, Nasazení, Kompletní odstranění, Maximální rozsah, Ask, Stejné parametry, Překladače celých vět, Podobný dialog, Podobný typ, Podobné parametry, Button, Confirm


Určitě si přečtěte

Google není jen vyhledávač: 15 užitečných funkcí, o kterých možná ani nevíte

Google není jen vyhledávač: 15 užitečných funkcí, o kterých možná ani nevíte

** Google umí kromě vyhledávání i spoustu dalších věcí ** Vybrali jsme více než 15 užitečných funkcí a schopností ** Stačí zadat do vyhledávače ta správná klíčová slova

Karel Kilián | 22

Karel Kilián
TipyVyhledávačeGoogle
Nejlepší notebooky do 20 000 Kč. Tipy, co se dnes vyplatí koupit

Nejlepší notebooky do 20 000 Kč. Tipy, co se dnes vyplatí koupit

** S cenou do 20 tisíc lze vybrat solidní notebook na práci i hry ** Přenosné notebooky nabídnou i kovová těla a rychlý hardware ** Možná největší problém je nedostupnost, nejžádanější kusy jsou vyprodané

David Polesný | 36

David Polesný
VánoceNotebooky
Vy a počítač: Virtuální plochy ve Windows mají smysl, používá je třetina čtenářů
Vladislav Kluska
Jak používáte počítačWindows 10Ankety
Vodafonu se zhroutila kabelovka. Síť bývalého UPC má výpadky
Lukáš Václavík
VodafoneUPC
Avast Omni: Krabička, která vám hackne síť a promění se v unikátní antivirus

Avast Omni: Krabička, která vám hackne síť a promění se v unikátní antivirus

** Počítač dnes ochrání kdejaký antivirus ** Drobná krabička Omni se postará rovnou o celou domácí síť ** Bude ji odposlouchávat, analyzovat a blokovat útoky

Jakub Čížek | 120

Jakub Čížek
AntivirusIoT
Nejlepší notebooky do 10 000 korun: Co má ještě smysl kupovat. A co ne?

Nejlepší notebooky do 10 000 korun: Co má ještě smysl kupovat. A co ne?

** Notebooky s cenou do deseti tisíc korun jsou plné kompromisů ** Existuje několik modelů dobře použitelných pro nenáročné použití ** Vhodnou alternativou jsou tablety nebo repasované počítače

David Polesný | 94

David Polesný
Jak vybrat notebookNotebooky

Aktuální číslo časopisu Computer

Megatest rychlých Wi-Fi 6 routerů

Jak ztišit počítač

Velký test mATX skříní