I was recently answering a question on StackOverflow when I began to think about a really common problem which is evident among the questions posted on SO. The problem is that sometimes, even after reading documentation and blogs, it’s not clear how to get an open-source library to do what you want. People can struggle for hours or days on these problems. This is the fundamental gist of many, many SO questions.
The two most common techniques that developers use to unblock their understanding are to read the docs and read the code. However, docs and code are only useful sources of “how-to” information when you already know what you are looking for. What about when the problem is that you aren’t sure where to start? In this case, an overall picture of the problem is required; one that enables the developer to see the high-level operation of the code, and then drill down into the specific areas of relevance. Once the developer’s attention is on the right areas of the code, then source code and docs help provide the last bit of understanding which is required in order to proceed.
AppMaps are a powerful tool that provides visualizations to help you understand just about any code, including open source libraries. It works by auto-generating interactive depictions of the code behavior that you are trying to understand.
Here’s a general strategy that you can use to understand just about any open-source code using the AppMap extension for VSCode:
- Write a program which exercises the code you want to understand.
- Run your program with the AppMap client library loaded and enabled.
- Start an AppMap recording, either programmatically or using the AppLand browser extension.
- Exercise your app, either graphically or through its API.
- Complete the recording and inspect the code structure, dependencies and flow.
As an example, a user recently asked the Stack Overflow community How to properly close a Net::SSH connection?. Net::SSH is a Ruby library that’s used to program the SSH protocol. This StackOverflow user wanted to go beyond the basic usage presented by the project web site, net-ssh generated documentation didn’t provide the answers.
To help answer this question, we prepared a test program that uses the Net::SSH library, and then recorded this program in action. The AppMap of this test program clearly shows how a Net::SSH connection proceeds through the following stages:
Configuration
Loading host keys
Startup message
Authentication, proceeding through auth methods None, public key, and password]
Command execution
Closing the session
By the way, it’s evident here the answer to the original question (how to close the connection) is to use Net::SSH::Connection::Session#close. This method is in the documentation, but there are 5 “close” methods in the documentation, and one “do_close”, so it’s understandable why the Stack Overflow user wasn’t sure which one to use. The AppMap makes it very clear what to do!
Top comments (0)