My story of learning source code and building open source tools
Hi there, my name is Bohdan, I work as JavaScript-developer. I’ve been learning source code (JavaScript and others) for almost 10 years already. In this article, I would like to tell you my story of developing tools to work with code and also present my latest Github-project codecrumbs.
Idea of the project
It all started exactly 2 years ago when I’ve decided to dig into React source code. Well, apparently it was not that simple task, I spent almost 3 months trying to understand it and build some picture in my head how all things work together. As result Under-the-hood-ReactJS project was born.
It had positive feedback from the community, so you can think about it as “successful”, but after I finished it I realized that my way of learning codebase was super inefficient. Take for example describing logic with flowcharts: I spent an enormous amount of time for creating schemes. Each time I made a new discovery from the code it affected the entire scheme instantly, forcing me to move and align ‘broken pieces’. Just repeated manual work. Super annoying, I needed to automate that somehow. So I created js-code-to-svg-flowchart. The library to convert any JavaScript code into SVG flowchart.
Analyzing my own experience of studying the source code of large projects, I came to the conclusion: it is not so difficult for me to understand a piece of code of a particular function as it is hard to see the “big picture”, to impose abstractions and to weed out non-important details. Every time I caught myself thinking that I am just jumping meaninglessly between files, often opening the same file several times, realizing that “oh, I already saw this, this is not the place” or “where is the right place I just saw. ”
So, I needed some kind of tool to mark important places in the code and ideally if it can build some “visual picture” of how everything works together. This is how the codecrumbs project (derived from “code” and “breadcrumb”) appeared — a tool that allows you to leave “bread crumbs” in the code and build a visual scheme from them.
Implementation
The project is a classic example of a client-server architecture with socket communication (everything is implemented with JavaScript). The server analyzes the project code and looks for comments containing “codecrumbs”, collects them and sends them to the client. The client imposes them on the project structure and draws a SVG image. There is support for “live updates”, so the process of use may be as follows: on one monitor — your code editor, on the other — the browser tab with the “codecrumbs” client. Write a comment — the scheme is rebuilt on the fly.
Features
Trail of breadcrumbs — a sequence of codecrumbs can be used to describe some data flow (e.g. user login, or form submit, etc.). Apply for one codebase or for multi-codebase integration — to study connections between sub-modules.
Dependencies tree — generate dependencies tree for an entry point. You can select connections and see “what is imported” and “its implementation”
Flowchart — builds SVG flowchart of selected file code (js2flowchart is used under the hood)
Share codecrumbs state — you can easily share your findings with others. Simply download the json file of codecrumbs store, send it to the friend, he/she can later upload it to the codecrumbs to see the same picture (even without having project locally).
Multi-language support — current version supports next programming languages:
- JavaScript
- TypeScript
- Python
- PHP
- Java
- C++ and others which use // as a comment :)
Future plans
The tool (codecrumbs) allows us to learn, document and explain a codebase much faster. Also, with Download & Upload feature it becomes super easy to collect and share your “investigation results”.
The ultimate goal is to have many case studies hosting at https://codecrumbs.io. The library of projects “Explained with codecrumbs”, the place for collaborative learning with real-world examples.
More features coming soon, stay tuned. Please put a “star” and share with friends, appreciate it :) Github-repo here https://github.com/Bogdan-Lyashenko/codecrumbs. Thanks!
If you liked this post and want to have updates about my next articles, please follow me on twitter @bliashenko!
