Documenteer je code

Geschreven door: op zaterdag 27 oktober 2018

Leestijd:

Documenteren van je code is uiteraard een best practice. De code op zich mag zo beschrijvend mogelijk zijn, zodat de documentatie impliciet is, maar bijvoorbeeld een uitleg over het waarom van een bepaalde functie of enkele code-voorbeelden zijn goede toepassingen van documentatie.

Documentatie zorgt er onder andere voor dat duidelijk is waarom iets is gemaakt, als dat vanuit de code niet direct duidelijk is, wat na jarenlang duizenden regels code schrijven voor iedereen geldt. Je zorgt er ook voor dat andere collega’s en zeker ook nieuwe collega’s snel begrijpen hoe de code werkt en toegepast wordt en waarom het is geschreven.

Er zijn de gebruikelijke inline comments, maar er zijn ook comments die een hele klasse of functie beschrijven. Dit kan je doen zoals je wilt, maar Microsoft gebruikt in .NET daarvoor XML Documentation Comments. Deze comments beginnen met drie slashes: /// en bevatten binnen die comment-blokken XML-elementen waarin je verschillende vormen van documentatie kan plaatsen, zoals een samenvatting, beschrijving van parameters en voorbeeldcode.

Een voorbeeld:


namespace WebApplication1.Utilities
{
    /// <summary>
    /// TextUtility provides easy methods to modify text.
    /// </summary>
    public class TextUtility
    {
        /// <summary>
        ///     Case me method changes text to upper case
        ///     </summary>
        ///     <example>
        ///     <code>
        ///         string t = "My text";
        ///         string TUPPER = TextUtility.CaseMe(t);
        ///         //TUPPER = "MY TEXT"
        ///     </code>
        ///     </example>
        ///    
        /// <param name="text">The string to change to upper case</param>
        /// <returns>string in UPPER CASE</returns>
        public static string CaseMe(string text)
        {
            return text.ToUpper();
        }
    }
}


In bovenstaande voorbeeld, wat een heel versimpeld voorbeeld is, wordt de class beschreven en de functie CaseMe. We zouden ook nog de namespace kunnen documenteren. Er staat een samenvatting, beschrijving van de argumenten en een voorbeeld.

Wanneer je deze XML-documentatie toevoegt, zie je deze hints ook in Visual Studio:

api-documentatie.png.png

Dit is handig voor in Visual Studio, maar je kan alle documentatie ook exporteren als XML-bestanden door bij het builden een project dit aan te geven. Dit bestand kan je daarna converteren met een tool als Sandcastle Help File Builder naar een website met daarin al je documentatie, zodat collega’s en andere ontwikkelaars snel de code als API kunnen naslaan:

voorbeeld-wiki-api.png

 

Zie voor meer informatie over documentatie: https://visualstudiomagazine.com/articles/2017/02/21/vs-dotnet-code-documentation-tools-roundup.aspx.


Andere blogartikelen

  • HTML tips voor mail templates

    Geschreven door: op zaterdag 10 november 2018

    Bij het bouwen van een e-mail template binnen HTML komen er veel dingen kijken, ik leg in deze post een aantal basiselementen uit hoe je om moet gaan met de HTML van een mail template, en hoe wij daar ...

    Bekijk het artikel »
  • 5 tips voor een succesvolle website

    Geschreven door: op vrijdag 5 oktober 2018

    Binnen een gestroomlijnd B2B sales proces spelen websites en online strategieën een essentiële rol. Met de juiste aanpak bereikt u als ondernemer de doelgroep. Maar hoe creëert u het juiste effe ...

    Bekijk het artikel »
  • Even voorstellen: Rowan Zomerdijk

    Geschreven door: op woensdag 3 oktober 2018

    Mijn naam is Rowan Zomerdijk sinds september ben ik werkzaam als UX developer bij Sigma Solutions. In mijn middelbare schoolperiode heeft mijn moeder een webshop gehad wat mij uiteindelijk deed kieze ...

    Bekijk het artikel »
Bel 072 5345 888
Meer dan 40 bedrijven vertrouwen op ons
Allrig is de alles in een leverancier binnen de energie-industrie
Aliancys is een toonaangevend wereldwijd bedrijf actief in de verkoop van kwaliteitsharsen
ERIKS is een toonaangevende en innovatieve leverancier aan de procesindustrie en aan machinebouwers, die zowel de rol van specialist als die van brede MRO-leverancier vervult
Industrieel dienstverlener Heinen & Hopman Engineering uit Bunschoten is dé wereldwijde specialist op het gebied van klimaatbeheersing
Handicare is een internationale organisatie die ouderen helpt om hun dagelijks leven gemakkelijker te maken door het produceren van hoogwaardige trapliften
Onze Middelen en Technologieën
microsoft silver partner
Adobe partner
fd-gazellen-2018.jpg
Google analytics
partners-logo.jpg