Dokumentációs kommentek

A jó kód jellemzője, hogy önmagát dokumentálja. Ezen kijelentés alapján sosem lenne szükség a kódunk dokumentálására. Azonban, mint sok más esetben, a gyakorlat itt is más, mint az elmélet. Adódhat olyan helyzet, hogy például egy programkönyvtárat fejlesztünk és nem szeretnénk a forráskódot mellékelni, csak magát a DLL fájlt és a dokumentációt.

Ebben az esetben az önmagát dokumentáló kód nem opció. Azonban könnyen generálhatunk dokumentációs kommenteket Visual Studio segítségével.

A dokumentációs kommentek hasonlóak a sima egysoros megjegyzésekhez (//), annyi különbséggel, hogy ezek két perjel helyett hárommal kezdÅ‘dnek, majd XML adat követi Å‘ket.

Ilyen kommentek osztályok, struktúrák, névterek, metódusok deklarációját megelÅ‘zÅ‘en helyezhetÅ‘ek el a kódban. A szükséges XML¹ tagokat, amiket ki kell töltenünk, a szerkesztÅ‘ automatikusan generálja.

Ha ezeket megfelelően kitöltjük, akkor a kód írása közben segítséget kapunk az elemekről felugró kis ablakban.

Példaként nézzük meg az alábbi példakódot:

using System;

namespace PeldaDoccomment
{
    /// <summary>
    /// Segéd metódusok
    /// </summary>
    static class Helpers
    {
        /// <summary>
        /// Számok összeadása
        /// </summary>
        /// <param name="szamok">Összeadandó számok</param>
        /// <returns>Számok összege</returns>
        public static double Ossszead(params double[] szamok)
        {
            double szum = 0;
            foreach (var szam in szamok)
            {
                szum += szam;
            }
            return szum;
        }
    }

    class Program
    {
        static void Main(string[] args)
        {
            double eredmeny = Helpers.Ossszead(12, 16);
            Console.WriteLine("Az összeadás eredménye: {0}", eredmeny);
            Console.ReadKey();
        }
    }
}

A program kimenete:

Az összeadás eredménye: 28

A Helpers osztály használata közben az alábbi dokumentációs segítséget kapjuk:

Build során lehetőségünk van az elkészült dokumentáció XML formátumba exportálásra is. Ehhez meg kell nyitni a projekt Properties oldalát, majd a Build résznél be kell kapcsolni az XML dokumentáció generálást és meg kell adni a kimeneti fájl helyét.

Az exportált XML fájl segítségével könnyen generálhatunk weblapot, Word dokumentumot, Súgót vagy MSDN-szerű dokumentációt. Erre szakosodott eszköz például a Sandcastle, ami a https://github.com/EWSoftware/SHFB címről szerezhető be.