Maakt Roslyn een einde aan handmatige documentatie?

In hoeverre kun je dit proces automatiseren? Is er een manier om documentatie automatisch te genereren uit broncode? Volgens software architect Michaël Hompus kom je een heel eind met het .NET Compiler Platform, dat ook wel als Roslyn bekend staat.

Deadlines versus documentatie

“In de praktijk zien we dat teams tegen verschillende uitdagingen aan lopen als het gaat om documentatie”, vertelt Michaël. “Ten eerste kost het tijd en moeite om goede documentatie te schrijven, en als je te maken hebt met deadlines, dan heeft het toevoegen van nieuwe features meestal prioriteit. Ook heb je te maken met verschillende eisen aan de documentatie, die afhankelijk zijn van de doelgroep waarvoor je schrijft. Denk aan eindgebruikers, collega’s, of nieuwe teamleden. Als schrijver van de code ken je de context en achtergrond. Voor een lezer is die informatie niet beschikbaar, waardoor documentatie soms lastig te begrijpen is. Tenslotte raakt documentatie vaak verouderd. Dit gebeurt als updates aan de code niet consequent worden doorgevoerd in de documentatie.”

Er zijn meerdere tools en methodieken beschikbaar om de documentatielast te verlichten. Veel .NET developers zijn bekend met het toevoegen van samenvattingen en beschrijvingen via speciale XML-tags in de code. Daarnaast bieden OpenAPI en AsyncAPI standaarden voor het beschrijven van API’s in JSON/YAML-formaat. Op basis van deze beschrijvingen kan een (interactieve) documentatiewebsite gegenereerd worden. Een hele andere manier is met behulp van de Specification by Example (SBE) methodiek gewenst systeemgedrag voor het schrijven van de code vast te leggen door middel van realistische voorbeelden.

Roslyn

Met Roslyn kan de volgende stap gemaakt worden, aldus Michaël: “Dit platform destilleert documentatie als het ware rechtstreeks uit de broncode. Roslyn is de codenaam voor het .NET Compiler Platform. Het biedt toegang tot zowel de C# en Visual Basic compilers waardoor de code geanalyseerd en getransformeerd kan worden.”

Roslyn maakt gebruik van een hiërarchische representatie van de structuur van broncode. Dit wordt gedaan in de vorm van een boomstructuur, die is opgebouwd uit nodes, tokens en trivia. Deze zogeheten ‘syntax trees’ helpen Roslyn om precies te bepalen waar in de code bepaalde statements en tokens gedefinieerd zijn en hoe ze zich tot elkaar verhouden. Daarmee kan er weer intelligentie uit de broncode worden gedestilleerd.

Laten we kijken naar deze voorbeeld-coderegel:

Console.WriteLine(“Hello world!”);

Intern kan deze gezien worden als een ‘CompilationUnit’ node, met een ‘UsingDirective’ child node, en een ‘ExpressionStatement’ node met daarin weer allerlei child nodes zoals voor Console, WriteLine, de string token, enzovoorts. v

Stukje van de “boom” waarin de code-regel ‘Console.WriteLine(“Hello World!”)’ word opgedeeld in nodes, tokens en trivia.

De boomstructuur van Roslyn helpt om de code te analyseren en zo te bepalen wat er op welke manier moet worden gedocumenteerd.

Michaël: “Hierdoor kan Roslyn veel interessante informatie uit de broncode halen. Denk aan welke classes en methoden gedefinieerd zijn. Maar ook parameters, return types en gebruikte namespaces. Die informatie kun je omzetten in nuttige documentatie zoals class diagrams, sequence diagrams, beschrijvingen van methoden en properties, en overzichten van dependencies.”

Voorbeeld van een diagram dat voortkomt uit de code, de verschillende services, command, events en condities worden weergegeven in een sequence diagram.

Wordt handmatige documentatie overbodig?

Gaat Roslyn handmatige documentatie volledig vervangen? “Dat verwacht ik niet, helaas”, aldus Michaël. “Het automatiseren van het proces kan zeker veel tijd en frustraties besparen, maar er blijft een zekere mate van handmatige input nodig. De kwaliteit van de gegenereerde documentatie staat of valt namelijk met hoe goed de broncode zelf-documenterend is. Ook moet de presentatie van de tekstuele en visuele output passen bij het doel en de doelgroep en dat vergt nu eenmaal maatwerk. Roslyn biedt vooral mogelijkheden om repetitieve documentatietaken te automatiseren, zodat diagrammen en beschrijvingen actueel blijven. Dat reduceert een hoop saai en foutgevoelig kopieer- en plakwerk. Voor de context, specificaties en architectuurkeuzes blijft handgeschreven documentatie essentieel.”

Op NDC London gaf Michaël een sessie over dit onderwerp, waarin hij onder meer een demo geeft van Roslyn en laat zien hoe je de gegenereerde documentatie visueel kunt opmaken, bijvoorbeeld met behulp van Markdown of PlantUML.