00:00:05.040
Thank you! Hi, I'm Kevin, and I'm here to teach your code to describe its own architecture.
00:00:14.639
What do you think of this quote: 'Documentation is the castor oil of programming? Managers think it's good for programmers, and programmers hate it.' It's true that we prefer to code; that's why we're developers. But what if we could transform a documentation problem into an accounting problem?
00:00:32.700
As a developer, when someone asks me for documentation, what I want to do is build a program that makes documentation. Making code that generates documentation doesn't feel like drinking castor oil; it feels like making robots, which is what we all love to do, right?
00:00:51.480
A bit more about me: you can think of me as an inventor using software as a medium. I started my career with C++ and Java in 1995, building early interactive web apps. I went on to start my first company in 2005 and joined the Ruby on Rails community in 2008.
00:01:15.420
In 2012, I founded a DevOps cybersecurity company called Conjure, which was acquired by a larger company in 2017. As we tried to integrate our cloud-first Rails app with their Windows data center product, we were really hampered by the lack of good architecture and co-design documentation. It was pretty disappointing and confusing.
00:01:36.540
We had good documentation for Conjure, which included a web service API server configuration, setup, high availability, and extensive test cases. So why was there still so much confusion among developers about what it did and how it worked? I think it's because we write documentation for a different audience, which is users. Even when we write good documentation and it's up-to-date, it doesn't help us too much.
00:02:19.040
There's a lot that we would like to learn and discover from docs and diagrams, but we can't because they were written with someone else's needs in mind. So, who is making these architecture and code design decisions? Well, we are. In 2021, the freedom to make decisions about code design belongs to developers; architecture is not something that's dictated by architects generally anymore.
00:02:40.140
Here are some results from a survey we're conducting called the state of software architecture quality. One of the questions we ask is: 'Who's primarily responsible for enforcing software architecture quality?' And the answer is: 68% of the time, it's developers, while only 18% are architects.
00:03:05.400
Since we developers own the decisions, we also have the responsibility to communicate and explain those decisions to other developers. What kind of documentation do we need as we work? We all play two roles when we work in code that we wrote ourselves: we play the expert role because we know how it works, and we're the go-to source for questions.
00:03:25.019
But when we work in code that we don't know, it's different; we play a newcomer role because it's unfamiliar. Documentation serves users, both internal and external, but usually not the people who work on the code. We need a new kind of documentation, which experts create with code as they work so that it's available when newcomers need it.
00:03:55.379
We also asked, 'Would you like to have up-to-date diagrams and visualizations of code structure?' and 84% said yes. Then we asked, 'Do you use existing code architecture and visualization tools, and would you like to keep using the tools you're using?' and 81% said no. So the data shows that we want up-to-date diagrams and visualizations that are useful to us in our work.
00:04:34.860
In a perfect world, what would we have available to us as we work? We would have docs and diagrams that are up-to-date, matching the code exactly. They should be interactive so that we can use docs like an app; static pictures don't scale. These docs would be contextual so that we can get exactly what's relevant to our task because, even when information is accurate, it's not useful if there's an overwhelming amount of it.
00:05:16.680
They should be as close to the code as possible because the code is where we work, and the code is our source of truth. We need to be able to move seamlessly back and forth between the code and our documentation app. With the remainder of this talk, I'm going to demonstrate a few tools that I think can take us in the right direction.
00:05:55.379
These are tools that automatically generate documentation and visualizations of architecture and code design. The framework to keep in mind is model-view-controller architecture because we all know models, views, controllers, and how they work together. I've chosen tools that auto-document the following things.
00:06:37.259
First, entry and ad flows: this is how we get the right context, for example, figuring out how a given web request uses particular tables or finding important functions performed by code, such as authentication, authorization, email, and background jobs in a particular service.
00:06:57.180
In essence, the named actions performed by the code. Second are web services, which are the commands sent to the app. Third is the data model, which interacts with the data store; it's what the app really does. From the standpoint of the user or the business, the operations that the code performs on the data store are much more important than the code itself.
00:07:54.720
I'll start with AppMap, which provides both high-level and low-level views of end-to-end code and data flows. If you want to follow along in the code or look it up later, I've created a fork of the Rails sample app, 6th edition. Within that fork is a branch called eager-lighting.
00:08:34.860
So, what is AppMap? AppMap is an OSS project that I created and I'm working on actively. AppMaps help you navigate and improve your code by showing you how it really behaves, feature by feature, as you work. It does this by recording code behavior into AppMap files during program execution. Then, you can visualize the AppMaps or analyze them using built-in analysis or your own custom code.
00:09:26.720
For Ruby, you install the AppMap gem and configure which source files and dependency gems you want to record. We record AppMap files by running code, such as test cases. This differs from static analysis, which only looks at your files on disk. AppMap records your code while it's running, so it knows exactly what happened at every point and how all the code, services, and data stores fit together.
00:10:05.399
To create AppMaps, you install and configure the AppMap gem, then run any code, such as a test case, while setting 'map equals true.' Let's take a live tour using the Rails sample app. I'll start by logging in. The function of this app is to make little Twitter-style micro-posts.
00:10:50.160
I've installed AppMap in the gemfile, and I've configured the Rails source directories and some selected dependency gems in our map.yml file. Now I can run any test with 'map equals true' to generate AppMaps. I'll run an integration test called 'users signup test.'