Papers
Topics
Authors
Recent
Gemini 2.5 Flash
Gemini 2.5 Flash
139 tokens/sec
GPT-4o
47 tokens/sec
Gemini 2.5 Pro Pro
43 tokens/sec
o3 Pro
4 tokens/sec
GPT-4.1 Pro
47 tokens/sec
DeepSeek R1 via Azure Pro
28 tokens/sec
2000 character limit reached

Interactive Diagrams for Software Documentation (2407.21621v1)

Published 31 Jul 2024 in cs.SE

Abstract: Getting acquainted with a large codebase can be a daunting task for software developers, both new and seasoned. The description of a codebase and its development should be the purpose of its documentation. However, software documentation, if it exists at all, is usually textual and accompanied only by simple static diagrams. It is also time-consuming to maintain manually. Even an API reference, which can be generated automatically from the codebase itself, has many drawbacks. It is limited to what it can extract from the codebase, is cumbersome to navigate, and fails to capture the interwoven nature of code. We explore an alternative approach centered around a node-link diagram representing the structure of a codebase. The diagram is interactive and filterable, providing details on demand. It is designed for automation, relying on static analysis of the codebase, and thus produces results quickly and offers a viable alternative to missing or outdated documentation. To evaluate this approach, we implemented a prototype named Helveg that is able to analyze and visualize C# code. Testing with five professional programmers provided feedback on the approach's benefits and challenges, which we discuss in detail.

Definition Search Book Streamline Icon: https://streamlinehq.com
References (58)
  1. Stack Overflow, “Stack Overflow Developer Survey,” 2023. [Online]. Available: https://survey.stackoverflow.co/2023/
  2. B. Dagenais and M. P. Robillard, “Creating and Evolving Developer Documentation: Understanding the Decisions of Open Source Contributors,” in Proceedings of the eighteenth ACM SIGSOFT international symposium on Foundations of software engineering, ser. FSE ’10.   Association for Computing Machinery, 11 2010, pp. 127–136. [Online]. Available: https://doi.org/10.1145/1882291.1882312
  3. GitHub, “Open Source Survey,” 2017. [Online]. Available: https://opensourcesurvey.org/2017/
  4. M. Cherubini, G. Venolia, R. DeLine, and A. J. Ko, “Let’s Go to the Whiteboard: How and Why Software Developers Use Drawings,” in Proceedings of the SIGCHI Conference on Human Factors in Computing Systems.   ACM, Apr. 2007, pp. 557–566. [Online]. Available: https://doi.org/10.1145/1240624.1240714
  5. D. Rost, M. Naab, C. Lima, and C. von Flach Garcia Chavez, “Software Architecture Documentation for Developers: A Survey,” in Software Architecture, K. Drira, Ed.   Springer, 2013, pp. 72–88. [Online]. Available: https://doi.org/10.1007/978-3-642-39031-9_7
  6. The Graphviz Authors. (1991, 09) Graphviz. [Online]. Available: https://graphviz.org/
  7. D. v. Heesch. (1997, 10) Doxygen. [Online]. Available: https://github.com/doxygen/doxygen
  8. N. Chotisarn, L. Merino, X. Zheng, S. Lonapalawong, T. Zhang, M. Xu, and W. Chen, “A Systematic Literature Review of Modern Software Visualization,” Journal of Visualization, vol. 23, no. 4, pp. 539–558, 08 2020. [Online]. Available: https://doi.org/10.1007/s12650-020-00647-w
  9. L. Bedu, O. Tinh, and F. Petrillo, “A Tertiary Systematic Literature Review on Software Visualization,” in 2019 Working Conference on Software Visualization (VISSOFT), 2019, pp. 33–44. [Online]. Available: https://doi.org/10.1109/VISSOFT.2019.00013
  10. I. Bacher, B. Mac Namee, and J. Kelleher, “The Code-Map Metaphor — A Review of Its Use Within Software Visualisations,” in Proceedings of the 12th International Joint Conference on Computer Vision, Imaging and Computer Graphics Theory and Applications.   SCITEPRESS - Science and Technology Publications, 2017, pp. 17–28.
  11. S. Eick, J. Steffen, and E. Sumner, “Seesoft—A Tool For Visualizing Line Oriented Software Statistics,” IEEE Transactions on Software Engineering, vol. 18, no. 11, pp. 957–968, Nov. 1992. [Online]. Available: https://doi.org/10.1109/32.177365
  12. M. Etter and F. Mehta, “CodePanorama: a language agnostic tool for visual code inspection,” in Proceedings of the 30th IEEE/ACM International Conference on Program Comprehension, ser. ICPC ’22.   New York, NY, USA: Association for Computing Machinery, Oct. 2022, pp. 225–228. [Online]. Available: https://doi.org/10.1145/3524610.3527874
  13. Microsoft, “Minimap — Visual Studio Code User Interface.” [Online]. Available: https://code.visualstudio.com/docs/getstarted/userinterface#_minimap
  14. C. Knight, “Virtual software in reality,” PhD Thesis, Durham University, 2000. [Online]. Available: http://etheses.dur.ac.uk/4244/
  15. R. Wettel and M. Lanza, “Visualizing Software Systems as Cities,” in 2007 4th IEEE International Workshop on Visualizing Software for Understanding and Analysis, 06 2007, pp. 92–99. [Online]. Available: https://doi.org/10.1109/VISSOF.2007.4290706
  16. G. Balogh, A. Szabolics, and A. Beszédes, “CodeMetropolis: Eclipse over the City of Source Code,” in 2015 IEEE 15th International Working Conference on Source Code Analysis and Manipulation (SCAM), Sep. 2015, pp. 271–276. [Online]. Available: https://doi.org/10.1109/SCAM.2015.7335425
  17. D. Moreno-Lumbreras, R. Minelli, A. Villaverde, J. M. González-Barahona, and M. Lanza, “CodeCity: On-Screen or in Virtual Reality?” in 2021 Working Conference on Software Visualization (VISSOFT), Sep. 2021, pp. 12–22. [Online]. Available: https://doi.org/10.1109/VISSOFT52517.2021.00011
  18. A. Schreiber and M. Misiak, “Visualizing Software Architectures in Virtual Reality with an Island Metaphor,” in Virtual, Augmented and Mixed Reality: Interaction, Navigation, Visualization, Embodiment, and Simulation, ser. Lecture Notes in Computer Science, J. Y. Chen and G. Fragomeni, Eds.   Springer International Publishing, 2018, pp. 168–182. [Online]. Available: https://doi.org/10.1007/978-3-319-91581-4_13
  19. C. L. Jeffery, “The City Metaphor in Software Visualization,” in Computer Science Research Notes.   Západočeská univerzita, 2019. [Online]. Available: https://doi.org/10.24132/CSRN.2019.2901.1.18
  20. M. Lanza and S. Ducasse, “Polymetric Views — A Lightweight Visual Approach to Reverse Engineering,” IEEE Transactions on Software Engineering, vol. 29, no. 9, pp. 782–795, Sep. 2003. [Online]. Available: https://doi.org/10.1109/TSE.2003.1232284
  21. C. Gutwenger, M. Jünger, K. Klein, J. Kupke, S. Leipert, and P. Mutzel, “A new approach for visualizing UML class diagrams,” in Proceedings of the 2003 ACM symposium on Software visualization, ser. SoftVis ’03.   Association for Computing Machinery, Jun. 2003, pp. 179–188. [Online]. Available: https://doi.org/10.1145/774833.774859
  22. U. Erdemir, U. Tekin, and F. Buzluca, “E-Quality: A Graph Based Object Oriented Software Quality Visualization Tool,” in 2011 6th International Workshop on Visualizing Software for Understanding and Analysis (VISSOFT), Sep. 2011, pp. 1–8. [Online]. Available: https://doi.org/10.1109/VISSOF.2011.6069454
  23. R. Müller and D. Zeckzer, “The Recursive Disk Metaphor - A Glyph-based Approach for Software Visualization,” in Proceedings of the 6th International Conference on Information Visualization Theory and Applications.   SCITEPRESS - Science and Technology Publications, 2015, pp. 171–176. [Online]. Available: https://doi.org/10.5220/0005342701710176
  24. K. Højelse, T. Kilbak, J. Røssum, E. Jäpelt, L. Merino, and M. Lungu, “Git-Truck: Hierarchy-Oriented Visualization of Git Repository Evolution,” in 2022 Working Conference on Software Visualization (VISSOFT), Oct. 2022, pp. 131–140. [Online]. Available: https://doi.org/10.1109/VISSOFT55257.2022.00021
  25. A. Štěpánek, D. Kuťák, B. Kozlíková, and J. Byška, “Interactive Diagrams for Software Documentation — Supplementary Material,” 2024. [Online]. Available: https://doi.org/10.5281/zenodo.13134466
  26. OMG, “Unified Modeling Language,” 02 2000. [Online]. Available: https://www.omg.org/spec/UML/1.3/PDF
  27. JetBrains. (2019, 04) UML class diagrams | IntelliJ IDEA. [Online]. Available: https://www.jetbrains.com/help/idea/class-diagram.html
  28. Visual Paradigm. (1999) Visual Paradigm. [Online]. Available: https://www.visual-paradigm.com/features/code-engineering-tools/
  29. S. Brown. (2018, 06) The C4 Model for Software Architecture. [Online]. Available: https://www.infoq.com/articles/C4-architecture-model/
  30. ——. (2020, 06) Structurizr. [Online]. Available: https://www.structurizr.com/
  31. M. Goertz. (2023, 03) Visualize dependencies with code maps — Visual Studio (Windows). [Online]. Available: https://learn.microsoft.com/en-us/visualstudio/modeling/map-dependencies-across-your-solutions
  32. Terrastruct. (2022) D2. [Online]. Available: https://github.com/terrastruct/d2
  33. ZEN PROGRAM. (2004) NDepend. [Online]. Available: https://www.ndepend.com
  34. CoderGears. (2009) JArchitect. [Online]. Available: https://www.jarchitect.com
  35. .NET Foundation. (2015) Docfx. [Online]. Available: https://github.com/dotnet/docfx
  36. G. Lato. (2020) Emerge. [Online]. Available: https://github.com/glato/emerge
  37. CodeSee. (2019) CodeSee. [Online]. Available: https://www.codesee.io/
  38. Swimm. (2020) Swimm. [Online]. Available: https://swimm.io
  39. M. Siriwardena. (2020) DependenSee. [Online]. Available: https://github.com/madushans/DependenSee
  40. S. Li and E. Xu. (2020, 03) Obsidian. [Online]. Available: https://obsidian.md/
  41. A. Štěpánek, “Extensible Visualization of C# Codebases,” Master’s thesis, Masaryk University, Faculty of Informatics, 2023. [Online]. Available: https://is.muni.cz/th/t0bse/
  42. K. Ng, M. Warren, P. Golde, and A. Hejlsberg, “The Roslyn Project: Exposing the C# and VB compiler’s code analysis,” Microsoft Corporation, white paper, 2012. [Online]. Available: https://www.microsoft.com/en-us/download/details.aspx?id=27744
  43. Microsoft, “NuGet.” [Online]. Available: https://www.nuget.org/
  44. ——, “MSBuild,” 2023. [Online]. Available: https://docs.microsoft.com/en-us/visualstudio/msbuild/msbuild
  45. ——, “Common Type System — .NET,” Jan. 2024. [Online]. Available: https://learn.microsoft.com/en-us/dotnet/standard/base-types/common-type-system
  46. J. Fuchs, P. Isenberg, A. Bezerianos, and D. Keim, “A Systematic Review of Experimental Studies on Data Glyphs,” IEEE Transactions on Visualization and Computer Graphics, vol. 23, no. 7, pp. 1863–1879, 07 2017. [Online]. Available: https://doi.org/10.1109/TVCG.2016.2549018
  47. Microsoft. (2022, 02) Visual Studio Image Library. [Online]. Available: https://www.microsoft.com/en-us/download/details.aspx?id=35825
  48. JetBrains. (2023) The State of Developer Ecosystem in 2023: C#. [Online]. Available: https://www.jetbrains.com/lp/devecosystem-2023
  49. H.-J. Schulz, “Treevis.net: A Tree Visualization Reference,” IEEE Computer Graphics and Applications, vol. 31, no. 6, pp. 11–15, 2011. [Online]. Available: https://doi.org/10.1109/MCG.2011.103
  50. Mozilla. Reason: CORS request not HTTP - HTTP | MDN. [Online]. Available: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSRequestNotHttp
  51. G. Plique. (2016) Graphology. [Online]. Available: https://github.com/graphology/graphology
  52. A. Jacomy and G. Plique. (2013) Sigma.js. [Online]. Available: https://github.com/jacomyal/sigma.js
  53. E. Reingold and J. Tilford, “Tidier Drawings of Trees,” IEEE Transactions on Software Engineering, vol. SE-7, no. 2, pp. 223–228, 03 1981. [Online]. Available: https://doi.org/10.1109/TSE.1981.234519
  54. M. Jacomy, T. Venturini, S. Heymann, and M. Bastian, “ForceAtlas2, a Continuous Graph Layout Algorithm for Handy Network Visualization Designed for the Gephi Software,” PLOS ONE, vol. 9, no. 6, 06 2014. [Online]. Available: https://doi.org/10.1371/journal.pone.0098679
  55. M. Bostock. (2010) D3: Data-Driven Documents. [Online]. Available: https://github.com/d3/d3
  56. Svelte. [Online]. Available: https://svelte.dev/
  57. J. Rosecký and A. Štěpánek. (2022) KAFE. [Online]. Available: https://gitlab.fi.muni.cz/legtvar/kafe
  58. Saalbach, Claudia and Schütt, Johannes, “survey.codes — SurveyAMC,” 2021. [Online]. Available: https://doi.org/10.5281/zenodo.4911339

Summary

We haven't generated a summary for this paper yet.

Ai Sparkles Streamline Icon: https://streamlinehq.com Summarize Now