I regret to report that I've just recently looked again at my programs for prime factors and tic-tac-toe, and they are entirely free of any sort of comments or documentation.
- Donald E. Knuth
Every programmer has repeatedly faced a situation when you have to read someone else's code without having an idea of what this or that function or class is for and how it is interconnected in general.
This happens even with their own programs and scripts written in write-only YP.
Developers who have a gift for working with such code are highly valued in the team.
There are such miraculous labyrinths from the code when the source code has:
- Inconsistent development style
- Overly complex and confusing program structure
- Obvious logical errors or omissions
- Neglect
You have to understand that there is a big difference between live working code and some educational and educational code. In the first case, the development process can be influenced by a variety of technical, commercial, and even domestic reasons. Under their influence, even the most austere and elegant software design can turn into spaghetti. The main reasons for this metamorphosis are familiar to many programmers.
- The very first and basic requirement for a working program is that it must be executed here and now, often on different devices and platforms. If you need to come up with strange workarounds due to restrictions imposed by domain policies, then these solutions will definitely be invented and implemented.
- Software development for AppleStore, the Wireguard example is pretty revealing.
- . , .
- , .
- PHP, JavaScript.
Fig. 1 Exploits of a mom .
Source code hermeneutics requires special skills and tools. Skills of this kind come only with experience, but a thorough knowledge of the syntactic features of the language and the accompanying documentation can make things easier for those who lack practical experience. Another such aid is dedicated source code research tools.
Sourcetrail to the rescue
Sourcetrail is an advanced interactive explorer and parser that allows you to actively explore your source code by indexing and collecting structure data. The application interface includes three main parts.
Fig. 2 Sourcetrail interface .
- Quick search and selection of indexed symbols in the source code. An autocomplete window will instantly provide an overview of all matching results across the entire codebase. Fuzzy search is supported.
- The graph displays the structure of the source code. The focus is on the currently selected symbol, the diagram explicitly indicates the inbound and outbound dependencies on other symbols.
- In the view code in a list displays all the pieces of source code for the currently selected character.
At startup, Sourcetrail prompts you to select a project. The set includes several educational and training courses for all supported languages. After selecting a project, Sourcetrail indexes the source code and then you can start working with the project.
Fig. 3 project selection .
Structures and classes are displayed in gray; packages, modules and namespaces - pinkish ; functions and methods are in yellow , and variables and scopes are in blue . Currently, the following programming languages are supported:
- C / C ++;
- Java;
- Python.
Fig. 4 method Run .
We selected the tictactoe_cpp project and then the Run method. Using the graph, you can clearly see that Run is called once from the main function. In addition to the vertices of the graph, the edges also carry a useful semantic load.
- Include text from file: green → green.
- Uses type: yellow → gray.
- Variable usage: yellow → blue.
- Function call: yellow → yellow.
Figure 5 designation of the edges of the graph .
In addition, there are definitions for overriding (left) and method inheritance (right).
Fig. 6 notation of edges for overriding and inheriting a method .
Sourcetrail strives to implement interactive behavior in every possible way. When you select graph objects in the code view, the corresponding symbols are automatically highlighted. The converse is also true, the choice of symbols in the code representation leads to an automatic readjustment of the graph. The selected item in the graph immediately moves to the center, and the content in the code pane is also updated. When you hover the cursor over graph objects, the corresponding symbols are highlighted with a rectangular frame. Again, the opposite is true for hovering over characters in the code pane.
You can set the level of detail and depth of the graph building using the trail controls in the upper left corner.
Fig. 7 graph display settings .
An interesting user interface concept for this class of applications is web browser-style navigation. In Fig. 2, the Back , Forward and Home buttons are visible . I must say - it is really convenient. The Refresh button does not redraw the graph, as one might expect, but suggests re-indexing the source code files. The Bookmarks button allows you to add a symbol to your favorites.
One of the trail controls is custom trail, at the very top. Calling the appropriate form, you can select the required compound graph, detail, starting and target nodes and type of construction.
Fig. 8 Building a graph with a custom trail .
Installing Sourcetrail
Sourcetrail is available for Windows, macOS and Linux. Windows users run setup.exe as usual, for macOS the installation takes place using standard operating system tools. For Linux, there are two options:
- download the .tar.gz package and then run the Sourcetrail.sh command;
- load the AppImage, grant execution permission with chmod + x filename and then just run it.
The settings will be stored in the following locations.
- Windows
- macOS ~ / Library / Application Support / Sourcetrail;
- Linux ~ / .config / sourcetrail.
The current version of Sourcetrail requires the Java 8 runtime to be installed to index Java projects. Sourcetrail binary architecture must match that of the JRE. Sourcetrail 32-bit requires a 32-bit JRE, and a 64-bit version of the application requires a 64-bit JRE, respectively.
Support for third party IDEs and editors
Sourcetrail supports integration with a variety of IDEs and text editors. All plugins are open source, development is carried out on github .
- Atom;
- CLion;
- Eclipse;
- Emacs;
- IntelliJ IDEA;
- Qt Creator;
- Sublime Text;
- Vim;
- Visual Studio Code.
CLI capabilities
Using the command line, you can index, or customize the project in Sourcetrail.
sourcetrail index [options...] projectfile
Possible options:
--help; --version; --project-file # .srctrlprj .
Project setup:
sourcetrail config [options...] --help; --indexer-threads # ; --use-processes #, C/C++ ; --logging-enabled #/ / ; --verbose-indexer-logging-enabled # , ; --jvm-path; --jvm-max-memory; --maven-path # maven; --jre-system-library-paths # jar JRE; --global-header-search-paths; --global-framework-search-paths; --show # ;
Summary
It is believed that developers spend most of their time making sense of existing code rather than writing new code. Source code analysis tools such as Sourcetrail can significantly tilt the balance in favor of the latter, without sacrificing quality. I would like to note the focus on a well-thought-out and familiar dynamic user interface, which perfectly plays the role of an unobtrusive assistant and significantly saves time on routine procedures.
