Code Diagrams - 3 Tools to Try

Daniel Warner — Thu, 13 Jun 2024 18:10:17 +0000

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.

AI Assisted Development: A Week in Tweets

Daniel Warner — Sat, 18 May 2024 00:26:35 +0000

The recent release of AppMap Navie has inspired thousands of people to install the AppMap extension, introducing them to AI-enabled development. This week, I have been using our X account to offer content that is not just promotional but also guides new users in expanding their understanding of both AppMap and AI-enabled development in general.

Brevity is key on X, so I tried to keep the message concise while still hitting the core concepts. Let me know how I did in the comments 😉 Here are the slightly more verbose versions...

Keep Your Data Up-to-date

Navie breaks through the 'black box' limitations of the chat interface by allowing you to include detailed context about your app with each question. This context is recorded as AppMap Data. The more current and comprehensive your AppMap data is, the more tailored the AI's answers will be to your coding scenario. By generating AppMap data in your dev environment, you gain the freedom to select which context is used to answer your question. Hence...

// Detect dark theme var iframe = document.getElementById('tweet-1790321204361932824-309'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1790321204361932824&theme=dark" }

Choose the right AI backend for the job

Navie uses GPT-4.5-Turbo as it's default LLM. It's a superb model. We love it. Our users love it. However, it might not always be the best fit. For instance, many large organizations forbid the use of public LLMs and provide their own in-house endpoints. In some cases, users prefer to run models specially tuned to specific jobs via platforms such as Ollama or LM Studio. Consequently, we've built in the capability to specify which LLM you want to use. Here is a demo using LM Studio...

// Detect dark theme var iframe = document.getElementById('tweet-1790827019560767872-7'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1790827019560767872&theme=dark" }

Ask questions in context

The entire AppMap team uses Navie daily, so the developer experience is something we strive to get right.

Weather I am looking for high-level architectural strategies or low-level generated code snippets I need Navie's answers to be at the right zoom level. This requires bundling up context wherever I am working and adding it to my question.

There are more than three ways to 'Ask Navie', but I picked the ones I use the most...

// Detect dark theme var iframe = document.getElementById('tweet-1791408370663993390-263'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1791408370663993390&theme=dark" }

I hope you'll find this helpful.

If you haven't tried AppMap Navie yet, join the party - it is available for free as a VS Code or JetBrain extension. Stay tuned for my next demonstration of Navie using a Nest.JS app!

Bonus

Thanks to Instagram user code.with_sahil07 for this great demo.

Thanks to Shani Shoham for including AppMap on his list of developer productivity tools.

DEV Community: Daniel Warner

Code Diagrams - 3 Tools to Try

1. Mermaid

2. PlantUML

3. AppMap

AI Assisted Development: A Week in Tweets

Keep Your Data Up-to-date

Choose the right AI backend for the job

Ask questions in context

Bonus