Poznáváme C# a Microsoft.NET 21. díl – komentování a dokumentace

Dnešní díl se seznámíme s možnostmi komentování kódu napsaným v jazyce C# a také s možnosti vytváření dokumentace. Pro nováčky se mimo jiné pozastavím nad tím co vlastně komentování zdrojového kódu znamená a proč se dělá.

Komentování kódu

Ve zdrojovém kódu se kromě výkonného kódu tj. kódu, který vykonává operace, mohou nacházet i dodatečné informace, které slouží pouze pro lidi, které daný kód čtou. Tyto informace jsou nazývány komentáře a pokud tento seriál sledujete, tak se komentáře vyskytovali ve všech zdrojových kódech příkladů.

Komentáře, jak název napovídá, slouží k okomentování určité části kódu, k popisu toho co daný úsek kódu provádí, abychom my, nebo někdo jiný, kdo po nás zdrojový kód bude číst, funkčnost onoho bloku rychleji pochopil. Při kompilaci jsou komentáře pochopitelně ignorovány.

Je známým programátorským zlozvykem přístup typu „tohle okomentuji později, až to pořádně otestuji“ nebo v tom horším případě „tohle si budu pamatovat a komentovat to nebudu“. Bohužel výsledek prvního rozhodnutí je mnohdy stejný jako u rozhodnutí druhého a tím výsledkem je, že kód zůstane neokomentovaný, což ovšem není dobře, protože si představte situaci, kdy napíšete nějakou třídu, jejíž metody neprovádějí zrovna triviální operace a vy si po půl roce, kdy tuto třídu budete chtít upravit budete říkat „co jsem to tady jenom dělal“ a nějaký čas vám pravděpodobně zabere, než onu funkčnost opět stoprocentně pochopíte. Nemluvě o projektech, na kterých pracuje více jak jeden člověk.

Běžné komentáře v C#

V C# jsou základní komentáře buď jednořádkové nebo víceřádkové.

Jednořádkové komentáře:

K vytvoření komentáře, který zabere pouze jeden řádek použijeme symbol dvou lomítek.

//jednoradkovy komentar

Víceřádkové komentáře:

Pokud chceme vytvořit komentář, který zabere více než jeden řádek a nechceme před každý řádek komentáře psát ona dvě lomítka, použijeme víceřádkový komentář.

/*
komentar
na vice
radku
*/

Takto by tedy mohlo vypadat použití těchto komentářů v praxi:

/*
Tato metoda
vraci soucet dvou
cisel typu int
*/
public int Secti(int a, int b)
{
  //secteni hodnot a vraceni vysledne hodnoty
  return a + b;
}

Dokumentace v XML

Kromě komentování kódu je také možné vytvořit dokumentaci k námi vytvořeným třídám. K tomuto účelu jazyk C# podporuje dokumentační formát založený XML. Pro ty co o XML slyší poprvé uvedu jen, že se jedná o zkratku eXtensible Markup Language (Rozšířitelný značkovací jazyk). Je to značkovací jazyk na první pohled podobný jazyku HTML, ale s podstatným rozdílem v tom, že XML definuje význam jednotlivých částí dokumentu, kdežto HTML definuje jejich vzhled.

Kompilátor pro C# umožňuje s použitím parametru /doc vygenerovat XML dokument obsahující dokumentaci našim třídám. Některé tagy (značky) jsou při kompilaci kontrolovány, ostatní představují pouze doporučení dané .NET frameworkem a při kompilaci jsou ignorovány. Výsledný XML dokument je velmi často pomocí XSL (eXtensible stylesheet language – jazyk určený k převodu XML do jiného formátu) transformace převeden na HTML stránku. XML dokument je také často využíván vývojovými prostředími pro zobrazování kontextových popisků při psaní zdrojového kódu. Následující tabulka obsahuje seznam používaných tagů pro vytváření XML dokumentačních komentářů v C#.

c Text, který představuje zdrojový kód
code Text, který představuje více řádek zdrojového kódu
example Pro uvedení příkladu použití členu popř. třídy
exception Slouží k uvedení výjimek, které mohou ve třídě nastat.
include Umožňuje se referencovat na jiný soubor s XML dokumentací, kde existuje popis k typům v našem zdrojovém kódu.
list Používá se pro uvedení výčtu hodnot
para Umožňuje strukturování text. Měl by se nacházet uvnitř tagů summary, remarks nebo returns
param Slouží k popisu parametru
paramref Indikuje, že uvedené slovo označuje parametr
permission Určuje viditelnost člena
remarks Umožňuje uvést doplňující informace o typu nebo jeho členovi.
returns Tato značka by měla uvádět popis návratové hodnoty
see Definuje odkaz na jiný programový element
seealso Definuje odkat na jiný programový element. Tento odkaz by měl být uveden v sekci See Also.
summary Uvádí základní informace o typu nebo jeho členovi.
value Používá se popisu hodnoty vlastnosti.

Značky exception, include, param, paramref, permission, see a seealso nebo přesněji některé jejich atributy jsou při kompilaci kontrolovány, ostatní jsou součástí doporučení pro dokumentaci v .NET frameworku. U značek exception, permission, see a seealso je kompilátorem kontrolován atribut cref, který referencuje nějaký typ a kompilátor zjišťuje, zda takovýto typ existuje. Při použití značek param a paramref je kontrolováno zda existuje daný parametr a u značky include kompilátor ověří existenci referencovaného XML dokumentu. Pokud tomu tak není kompilace neskončí chybou, ale kompilátor vás na tuto skutečnost upozorní varováním.

Jako příklad pro lepší pochopení si uveďme jednoduchou třídu zaměstnanec, na které demonstruji použití některých XML dokumentačních komentářů.

using System;

namespace PrikladyZive21
{
  /// <summary>
  /// Trida predstavujici zamestnance
  /// slouzici k demonstraci XML
  /// dokumentacnich komentaru
  /// </summary>
  public class Zamestnanec
  {
    private int vek;
    private string jmeno;
    private string prijmeni;
    private int hodinovaSazba;

    /// <value>
    /// Vek zamestance
    /// </value>
    public int Vek
    {
      get
      {
        return vek;
      }
      set
      {
        vek = value;
      }
    }
    /// <value>
    /// Jmeno zamestnance
    /// </value>
    public string Jmeno
    {
      get
      {
        return jmeno;
      }
      set
      {
        jmeno = value;
      }
    }
    /// <value>
    /// Prijmeni zamestnance
    /// </value>
    public string Prijmeni
    {
      get
      {
        return prijmeni;
      }
      set
      {
        prijmeni = value;
      }
    }

    /// <value>
    /// Hodinova sazba zamestance
    /// </value>
    public int HodinovaSazba
    {
      get
      {
        return hodinovaSazba;
      }
      set
      {
        hodinovaSazba = value;
      }
    }

    /// <summary>
    /// Konstruktor ocekavajici jmeno a prijmeni zamestance.
    /// Parametr <paramref name="jmeno">jmeno</paramref> i <paramref name="prijmeni">prijmeni</paramref>
    /// jsou typu <see cref="String"/>
    /// </summary>
    /// <param name="jmeno">Jmeno zamestance</param>
    /// <param name="prijmeni">Prijmeni zamestance</param>
    public Zamestnanec(string jmeno, string prijmeni)
    {
      this.jmeno = jmeno;
      this.prijmeni = prijmeni;
    }

    /// <summary>
    /// Metoda pro vypocet mzdy zamestance.
    /// <example>
    ///  Priklad pouziti :
    ///  <code>
    ///  Zamestnanec instance = new Zamestnanec("Tomas","Kutin");
    /// instance.HodinovaSazba = 65;
    /// int lMzda = instance.VypocetMzdy(100);
    ///  </code>
    /// </example>
    /// </summary>
    /// <param name="pocetOdpracovanychHodin">Pocet odpracovanych hodin</param>
    /// <returns>Vysledna mzda</returns>
    public int VypocetMzdy(int pocetOdpracovanychHodin)
    {
      return pocetOdpracovanychHodin * hodinovaSazba;
    }
  }
}

Jak jsem psal, tak některá vývojová prostředí umí vygenerovaného XML souboru s dokumentací využít pro zobrazování kontextové nápovědy při tvorbě kódu. Na obrázku můžete vidět, jak je vytvořená dokumentace zobrazována v prostředí Visual C# .NET.

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

Kontextová nápověda ve Visual C# .NET

K vygenerování dokumentace pro uživatele našich tříd nejčastěji použijeme XSL transformaci do formátu HTML. Sobory XSL můžete nalézt na internetu, nebo si je vytvořit sami. V souborech pro stažení jeden takovýto soubor naleznete. Na obrázku níže vidíte jak může vypadat XML soubor s naší dokumentaci po XSL transformaci do HTML.

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

Html verze dokumentace ke třídě Zamestanec

Zdrojové kódy k příkladům naleznete zde.

Další díl seriálu věnuji uživatelsky definovaným konverzím.

Diskuze (8) Další článek: Výstava mikroprocesorů v pražském technickém muzeu

Témata článku: Software, Microsoft, Programování, Public, Dokumentace, Private, Podobný jazyk, Díl, Komentování, Dok


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

Biblická potopa Česka: Jak bychom dopadli, kdyby nás zatopil oceán

Biblická potopa Česka: Jak bychom dopadli, kdyby nás zatopil oceán

** Představte si biblickou potopu ** Nejprve zaniknou Děčín a Břeclav, pak i Brno a Praha ** Hlavním městem se stane Jihlava a zbytky Čechů přežijí na Kvildě

Jakub Čížek | 91

16 tipů a vychytávek, se kterými dokonale ovládnete komunitní navigaci Waze

16 tipů a vychytávek, se kterými dokonale ovládnete komunitní navigaci Waze

** Waze není jen navigace – je to i sociální síť s dopravními informacemi ** Mobilní aplikace skýtá široké možnosti nastavení ** Vybrali jsme pro vás 16 nejzajímavějších tipů a triků

Karel Kilián | 48

Google Coral: Raspberry Pi s čipem, který zpracuje 4 biliony operací za sekundu

Google Coral: Raspberry Pi s čipem, který zpracuje 4 biliony operací za sekundu

** Je to velké jako Raspberry Pi ** Ale je to až o několik řádů rychlejší ** Dorazil nám exotický Google Coral s akcelerátorem Edge TPU

Jakub Čížek | 18

Zranitelnost platebních karet Visa umožňuje zločincům obejít limit při bezkontaktních platbách

Zranitelnost platebních karet Visa umožňuje zločincům obejít limit při bezkontaktních platbách

** Odborníci přišli na to, jak obejít limit bezkontaktních plateb ** Stačí zařízení, ovlivňující komunikaci mezi kartou a terminálem ** Stahují se nad bezkontaktními platbami mračna?

Karel Kilián | 79

20 tipů a triků pro Gmail: Užitečné maličkosti, které zefektivní práci s e-maily

20 tipů a triků pro Gmail: Užitečné maličkosti, které zefektivní práci s e-maily

** V Gmailu je řada užitečných funkcí, které možná všechny neznáte ** Odeslání mailu můžete například pozdržet či naplánovat na později ** Nad Gmailem můžete mít s několika triky daleko lepší kontrolu

Karel Kilián | 25



Aktuální číslo časopisu Computer

Speciál o přechodu na DVB-T2

Velký test herních myší

Super fotky i z levného mobilu

Jak snadno upravit PDF