Codecrumbs - a new way of learning and documenting source code
Tags: javascript, python, learning, opensource
Published: 2019-02-18 21:40:58

---
title: Codecrumbs - a new way of learning and documenting source code
published: true
description: codecrumbs - visual tool for learning a codebase by putting breadcrumbs in a source code
tags: javascript,python,learning,opensource
---
> **TL;DR** Hi there. My name is Bohdan and I am studying problems of reading code. I just finished working on the first version of "codecrumbs"- visual tool for learning a codebase by putting breadcrumbs in a source code. Check out [github repo here](https://github.com/Bogdan-Lyashenko/codecrumbs).
<img src="https://thepracticaldev.s3.amazonaws.com/i/ywbbz34pmkkf35qxj8ba.png"/>

## Reasoning
Recently I conducted a survey about main challenges we are facing when start learning a big codebase (if you haven't submitted your answers yet, you can still
 do it [here](https://goo.gl/forms/n0SjqMQ27DLDfP6I2)). The question about "elephant in the room" is particularly interesting, just have a look:
<img src="https://thepracticaldev.s3.amazonaws.com/i/ia9iyg7k5w7f4db7kipu.png"/>
The trend is quite clear already (and that was obvious before) - it's way harder to "connect dots" and "get the big picture" than just understand the code of particular function or file (so, that means code editors don't help much here). In the unknown codebase we get lost easily and start jumping between files without a clear understanding of what we are doing. It’s just too much useless noise, too many details which blur our vision and understanding of code. 

So we need some way to **diminish the noise** of the big codebase and **highlight important spots** in the codebase. A visual tool is a good way to solve that if:
- it gives the right perspective (and not just to make it look fancy)
- in fact, reduces useless details (and doesn't add one more, visual)
- it is easy to use with existing codebases without a need to rewrite the code

## Codecrumbs for rescue
So I've built [codecrumbs](https://github.com/Bogdan-Lyashenko/codecrumbs) (the name combines "code" and "breadcrumb"). It's a visual tool which gives you what text-based code editor misses - a bigger view of the entire codebase.

How does it work? You run codecrumbs command for a codebase, it analyzes source code and builds its visual representation. Write down a codecrumb-comment and codebase state will be reflected by a visual client in browser 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.).
<img src="https://cdn-images-1.medium.com/max/800/1*OTbzqtV0UxTq_OLkoMfHMw.gif"/>

Dependencies tree - generate dependencies tree for an entry point. You can select connections and see “what is imported” and “its implementation”
<img src="https://cdn-images-1.medium.com/max/1400/1*nW72xtwWP4cKcBoWsoQ7wg.png"/>

Flowchart - builds SVG flowchart of selected file code ([js2flowchart](https://github.com/Bogdan-Lyashenko/js-code-to-svg-flowchart) is used under the hood)
<img src="https://cdn-images-1.medium.com/max/1400/1*0AoFj03FeYs6eqKIhl0f0w.png"/>

Multi-codebase integration - helps to study connections between several codebases (sub-modules).
<img src="https://raw.githubusercontent.com/Bogdan-Lyashenko/codecrumbs/master/docs/multi-l-c.png"/>

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).
<img src="https://raw.githubusercontent.com/Bogdan-Lyashenko/codecrumbs/master/docs/upload-feature-2.gif"/>

Multi-language support - current version supports the 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!