loading...

Codecrumbs - a new way of learning and documenting source code

bogdanlyashenko profile image Bohdan Liashenko ・3 min read

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.

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). The question about "elephant in the room" is particularly interesting, just have a look:

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 (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.).

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)

Multi-codebase integration - helps to study connections between several codebases (sub-modules).

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 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!

Discussion

markdown guide
 

Looks very prominent. I'll give it a try.
For Java community it would be nice to have the tool integrated within IntellijIdea and Eclipse IDE. It is unlikely I'll install node js and will be commenting in the code from external tool.

 

Thanks for the feedback. Yeah, make sense, that shouldn’t be too hard to implement, will add to backlog.

 

I've been looking for a tool like this one for a longtime, thanks for putting this together!

 

Thanks:) Stay tuned, it’s getting even more cool features soon.

 

And here I was, drawing all this on pieces of paper! Looks super cool