How to navigate the maze of JavaScript code

TL;DR In this article I want to highlight the problem of navigating a big codebase and to show a little demo of codecrumbs — visual tool which helps you to learn a codebase faster. You can see standalone version online here. Appreciate your early feedback!

Idea

We, as programmers, are super inefficient when we jump into a big codebase, or codebase we know nothing about. It’s a code maze. We get lost easily and start drifting between files in complete darkness. It’s just too much useless noise, too many details which blur our vision and understanding of code. You can check my recent article where I highlighted the problem of reading code with some more thoughts.

So we need some way to:

• diminish the noise of the big codebase
• highlight important spots in the big codebase
• and even guide us through the big codebase

A visual tool is a good way to solve that if:

• it gives the right perspective (and not just make it look fancy)
• in fact, reduces useless details (and not adding one more, visual)
• it is easy to use with existing codebases without a need to rewrite the code

All of these, I believe, can be solved by codecrumbs. Still, much work to do, but the basic features are already implemented. Let’s have a look!

Super simple integration

So, let’s pick up some project we can use for example. I’ve chosen “Todo app with Create React App, React Redux, and Firebase” because it’s simple enough to not be overwhelming, and at the same time, it has enough files structure (55 files, 20 folders) to look like a real project.

Install codecrumbs globally or in devDependencies:

yarn add codecrumbs -D

Add command with entry file and source directory to scripts section in your package.json:

“start:cc”: “codecrumbs -e src/index.js -d src”

Run yarn start:cc from the terminal. Now it’s running and watching the code changes! Open http://localhost:2018/# in the browser to see what you got.

Breadcrumbs in the code maze

The “killer feature“ of the tool hides behind the “CodeCrumbs” toggle. Let’s enable it. Now we can leave breadcrumbs in the code and they will appear on a scheme. On the fly. To do so, simply write down comment.

Example of putting the first breadcrumb

Let’s open src/view/app/app.jsand write //cc:here . In this example,cc (stands for CodeCrumb) is the prefix which used by the parser, and ‘here’ is a title of our first breadcrumb.

You can see that one more file was added to the scheme, the file which we marked as “important” by writing down the codecrumb there. Also, I want to highlight that all codebase is still there, you can expand folders and see other files, but you always can close them to filter only key-files for us. That’s what I call “reducing the noise”.

Example of putting the trail of breadcrumbs

Also, you can create “trail of breadcrumbs” — basically, a sequence of codecrumbs which follow some data flow (e.g. user login, or form submit, etc.). Let’s see the example with a sign in.

To create a codecrumb as part of a trail you write: //cc:signin#0;dispatch action where signin is the trail ID, #0 order number of step, ‘dispatch action’ is a title describing the step. Let’s add few more. You can see all of them here.

Other features

Let’s do a quick walk through other main features.

Dependencies

Another “big thing” is Dependencies tree. When you select a node (file) the request will be sent to the local server, returned with generated dependencies tree for an entry point. You can select connections and see “what is imported” and “its implementation”.

Flowchart

js2flowchart is used in the sidebar to draw flowchart for the selected file code

Learn easy — share your knowledge easy

So let’s say you put together some trail of codecrumbs describing some important flow inside the project. How you can share it with other? Simply download the json file of codecrumbs store, send it to the friend, he/she uploads it to the codecrumbs and can see same you just saw!

Download

Upload

More to come

There are several big features I work on right now, but soon they will be finished as well. In meanwhile, have a look at https://github.com/Bogdan-Lyashenko/codecrumbs and let me know what you think. Ideas and improvements are welcome. Thanks.

If you liked this post and want to have updates about my next articles, please follow me on twitter @bliashenko!