A new look at learning and documenting source code

    TL; DR Hello. My name is Bogdan and I am studying the problems of reading code. I just downloaded the first working version of codecrumbs, a visual tool for learning source code with breadcrumbs. The github repository can be viewed here.

    image

    Problem


    Recently, I conducted a survey about the main problems that we face when we begin to study the source code of a large project (if you have not yet participated, then you can still complete the survey here ).

    The main question that interested me was: what exactly is the hardest part of learning the code for a new project for you? Let's look at the trend of responses in the picture below.

    image

    As expected, it is much more difficult to combine all the points into a single picture than to understand what the code does inside a particular function or file (oddly enough, code editors pay much more attention to just one file, not the whole picture "). The problem is that when we first open the project code, too much information is dumped on us at a time. We start to jump between files meaninglessly, in complete chaos, 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 that I just saw ”And wasting time. So, we definitely need some kind of tool to mark important places in the code and, ideally, to build that very “general visual picture” of how everything works.

    Codecrumbs to the rescue


    Codecrumbs (the name is derived from “code” and “breadcrumb”) is a tool that allows you to leave “bread crumbs” in the code and build a visual diagram on them.

    How it works? You execute the codecrumbs command specifying the paths to the project code, codecrumbs analyzes the source code and creates its visual representation. Add codecrumb-comment and the updated status of the code base will be displayed in the visual client in the browser on the fly.

    Key features


    Trail of breadcrumbs ("chain of crumbs") - a sequence of crumbs that describe some kind of scenario inside the application (for example, authentication or submitting a form to the server, etc.).

    image

    Dependencies tree (“tree of dependencies”) - makes it easy to determine “what is being imported”.

    image

    Flowchart (“flowchart“) - allows you to see the flowchart of the selected file.

    image

    In addition, just by running “codecrumbs” for several projects at the same time, you can study their integration with each other.

    image

    After all this, you can also download and “send to a friend” the scheme that you just learned. Use the “download” function to get the current state of the application in json file format. The file will contain the minimum amount of data to display the circuit. For this, it is not necessary to have the same source code locally - “codecrumbs” can work in “standalone” mode in the browser. An example is here .

    image

    Language support. The following programming languages ​​are supported in the current version:

    • Javascript
    • TypeScript
    • Python
    • Php
    • Java
    • C ++

    JavaScript offers more functionality than the rest, since it alone uses the AST parser to process the code.

    Future plans


    This tool (codecrumbs) allows you to study, document and explain the code base faster. In addition, the “download / upload” function makes it very easy to distribute the results of code research. The ultimate goal is to place a lot of such “cases” on https://codecrumbs.io and get something in the style of the Explained with codecrumbs project library - a place where everyone can share knowledge on examples of real projects.

    More cool features coming soon, stay tuned! And yes, click “star” and tell your friends :) The Github repository is here github.com/Bogdan-Lyashenko/codecrumbs . Thanks!

    Also popular now: