The most useful tools for diagramming code create visuals from source that can be integrated into a code-centric development workflow.

Stand-alone visual editors sit too far outside the workflow to be useful. Switching context between a development environment and a diagramming application opens a gulf that condemns diagrams to be out-of-date and update-resistant from the moment they are created.

There are three tools I have used that do an excellent job of solving this issue:

1. Mermaid

Mermaid is a JavaScript-based diagramming and charting tool that makes it easy to create diagrams from text descriptions. It's particularly useful for generating flowcharts, sequence diagrams, and class diagrams.

Mermaid integrates seamlessly with Markdown, which is handy, but the thing I like most about Mermaid is that it feels lightweight. Once you have imported the library, a mermaid chart can be embedded in HTML with pre tags and themed by tweaking properties in a snippet of JS.

There is a large community of Mermaid users. It’s a strong FOSS project that is worth checking out.

Key Features:

• Easy-to-Learn Syntax: Get started quickly with a simple syntax.
• Community Support: Extensive documentation and an active community offering support and plugins.
• Browser Rendering: Renders directly in the browser with minimal dependencies.

2. PlantUML

PlantUML, like Mermaid, is an open source tool that allows users to create diagrams from plain text descriptions. PlantUML is the original ‘diagrams as code’ platform. It has a deep feature set, can be integrated into just about any environment, and can be extended to fit just about any use case. For example, the most useful thing to me about PlantUML is its support for visualizing .JSON files.

Key Features:

• Wide Range of Diagrams: Supports a large range of diagrams, making it versatile for different documentation needs.
• Integrations: Yes, someone has probably built a PlantUML integration with that tool you are using.
• Multiple Output Formats: Offers formats such as PNG, SVG, and LaTeX, making it possible to share diagrams in different contexts.

3. AppMap

AppMap is an open source code editor extension that records and visualizes the runtime behavior of your application. It captures real-time data about your application's code, making it easier to understand how different components interact. This is particularly valuable for debugging, performance tuning, and ensuring that your application behaves as expected. AppMaps can be exported to SVG or JSON and has a deep set of integrations making it easy to integrate at any point in the software development lifecycle.

I'm biased because I helped build it, but the best thing about AppMap is that the diagrams are derived automatically from the code’s behavior. There isn’t a step where you have to go and manually create the diagram.

Key Features:

• Interactive Diagrams: Explore the dynamic interactions between different parts of your application.
• Integrated in the Development Workflow: You can generate diagrams at any point from your dev environment or CI. There are supported integrations with Confluence, GitHub Actions, SwaggerHub, Postman, Docker and more.
• Performance and Security Insights: AppMap will alert you to problematic areas of your code.

Each of these tools offers unique strengths, depending on your specific needs. Give them a try and see how they can enhance your code visualization efforts.

If you have already tried them, please share your thoughts and experiences with these tools in the comments. It would be interesting to hear which one you landed on and why.