Gebruik je broncode als documentatie voor je stakeholders

Presentatie van Michaël Hompus tijdens het devNetNoord event op 31 oktober 2024 in het Gasunie gebouw.

Transcript

1. Use your source code to document your application Michaël Hompus
2. [ ][/@]eNeRGy164 Michaël Hompus Architect @ Info Support Microsoft MVP [ ][/@]eNeRGy164
3. [ ][/@]eNeRGy164 Two goals How to inspect our dotnet source code using Roslyn How to generate documentation with that knowledge
4. [ ][/@]eNeRGy164 Agenda Challenges Existing solutions Roslyn Generate documentation
5. Challenges
6. [ ][/@]eNeRGy164 Who is your (documentation) stakeholder? Product owner Operator Team Other teams / community Customer You
7. [ ][/@]eNeRGy164
8. [ ][/@]eNeRGy164 Challenges • Creating meaningful documentation takes time and effort • Writing documentation does not feel as an improvement, as writing more code • At the time of writing, you already understand the current state of the application • People forget to update the documentation after changing the code • Your stakeholders cannot read (your) code • If people discover that documentation is not accurate, they will never trust it
9. [ ][/@]eNeRGy164 Or… • With generative AI, you are no longer writing your code yourself, but you still want to document & inspect what it does!
10. Existing solutions
11. [ ][/@]eNeRGy164 Existing solutions • XML Documentation Comments – IDE code completion – “MSDN like” documentation – DocFX, Sandcastle, Doxygen • OpenAPI (a.k.a. Swagger) – Machine-readable RESTful API description – As a consumer you can generate a client for the API – Swagger UI allows you to read & interact with an API – Can show payload examples
12. [ ][/@]eNeRGy164 • A living document is a document that is continually edited and updated – Wikipedia • Suggested reading – Living Documentation by Cyrille Martraire Living Documentation
13. [ ][/@]eNeRGy164 However… • Output is as descriptive as the input of the developer • Generated files are not (easily) accessible – Source control – Hidden path in website – Artifact in your build pipeline • To generate readable and up-to-date documentation, it must be part of a pipeline
14. Roslyn
15. [ ][/@]eNeRGy164 Roslyn Roslyn is a set of open-source compilers and code analysis APIs for C# and Visual Basic languages – Wikipedia Also known as “.NET Compiler Platform SDK” “ ”
16. [ ][/@]eNeRGy164 Syntax trees • Syntax trees represent the lexical and syntactic structure of source code – Syntax Trees › Syntax Nodes › Syntax Tokens › Syntax Trivia • Spans – Position and length within the source text of a Node, Token or Trivia
17. Demo ConsoleApp1 Roslyn Parse Syntax Tree
18. [ ][/@]eNeRGy164 • Compilation – Representation of everything needed to compile a C# or Visual Basic program, which includes all the assembly references, compiler options, and source files • Symbols – Represents a distinct element declared by the source code or imported from an assembly as metadata • Semantic Model – Represents all the semantic information for a single source file Semantics
19. [ ][/@]eNeRGy164 • Descends an entire graph of Syntax Nodes – CSharpSyntaxVisitor › CSharpSyntaxWalker › CSharpSyntaxRewriter • Visitor pattern – Override the appropriate Visit* method SyntaxWalkers
20. Demo Roslyn Walk Trees
21. [ ][/@]eNeRGy164 Workspaces • You can compare a workspace to an IDE, like Visual Studio
22. [ ][/@]eNeRGy164 Load solutions & projects MSBuildworkspace NuGet • Microsoft.CodeAnalysis.Workspaces.MSBuild • Microsoft.CodeAnalysis.CSharp.Workspaces • Microsoft.Build.Locator Faster Can reuse previous builds Does not support all project types Brittle with different dotnet generations Buildalyzer NuGet • Buildalyzer.Workspaces ' Supports more project types Slower Removes current build output
23. Generate documentation
24. [ ][/@]eNeRGy164 Generate documentation • There is no generic solution • Very specific for your project and stakeholders
25. [ ][/@]eNeRGy164 Plain text can be powerful Markdown Markdown is a lightweight markup language with plain text formatting syntax AsciiDoc AsciiDoc is a human- readable document format using plain-text mark-up conventions PlantUML PlantUML is an open-source tool allowing users to create UML diagrams from a plain text language
26. [ ][/@]eNeRGy164 Plain text can be powerful Markdown Markdown is a lightweight markup language with plain text formatting syntax AsciiDoc AsciiDoc is a human- readable document format using plain-text mark-up conventions Mermaid Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams.
27. [ ][/@]eNeRGy164 DendroDocs Solution JSON File Render Application Project Specific Tool Aggregate Renderer Event Flow Renderer … Renderer AsciiDoc PlantUML Markdown Analyzer dotnet tool
28. [ ][/@]eNeRGy164 DendroDocs Solution Analyzer dotnet tool JSON File Render Application Project Specific Tool Aggregate Renderer Event Flow Renderer … Renderer AsciiDoc PlantUML Markdown Project Analyzer JAR
29. [ ][/@]eNeRGy164 Pitstop • dotnet sample application with microservices, CQRS, DDD, etc… • https://github.com/EdwinVW/pitstop Photo by Thomas Moerkerken
30. [ ][/@]eNeRGy164 Pitstop
31. [ ][/@]eNeRGy164 Analyzing
32. Demo Pitstop Documentation Renderer
33. [ ][/@]eNeRGy164
34. [ ][/@]eNeRGy164
35. [ ][/@]eNeRGy164 Events with consequences • Show the consequences of receiving an event
36. [ ][/@]eNeRGy164 Branching logic • Show conditions • Wrap a condition in a variable with descriptive name
37. [ ][/@]eNeRGy164 Entities • Show interactions with entities
38. [ ][/@]eNeRGy164 Sagas • Show start trigger(s) • Show events that will continue the flow
39. [ ][/@]eNeRGy164 State machine • Show possible transitions with associated events
40. [ ][/@]eNeRGy164 Insights • Gain insight where unexpected dependencies are emerging
41. [ ][/@]eNeRGy164
42. [ ][/@]eNeRGy164
43. [ ][/@]eNeRGy164 3D
44. [ ][/@]eNeRGy164 Two goals
45. [ ][/@]eNeRGy164 get creative!
46. [ ][/@]eNeRGy164 start generating documentation!
47. [ ][/@]eNeRGy164 GitHub • DendroDocs A starting point to generate documentation from code – https://github.com/dendrodocs – https://www.nuget.org/packages?q=DendroDocs • LivingDocumentation Workshop Get hands-on with Roslyn and generation of documentation yourself – https://github.com/eNeRGy164/LivingDocumentation.Workshop • PlantUML Builder StringBuilder extension methods to make it easier to generate valid PlantUML diagrams – https://github.com/eNeRGy164/PlantUml.Builder – https://www.nuget.org/packages/PlantUml.Builder
48. Thank you! [ ][/@]eNeRGy164