Table of Contents

Do you write code 100% of your job time?

I’m guessing the answer is no. Ignoring the whole management part, meetings, coffee, youtube, cats, etc, even if you’re sitting at your keyboard you’re not typing all the time. So what else are you doing?

The short answer: you’re probably figuring out what to write and where to add new features (and what to fix)… so you’re mostly reading and trying to understand the code.

There are tools to help you better understand code which are not just text editors. One of such application is Sourcetrail, let’s see what can it do for us.

Unfortunately, as of late 2021 the project was closed, see this blog post from the authors: Discontinue Sourcetrail – Sourcetrail Developer Blog.

Bonus!, read further to see details of our new giveaway :)

Promo note: This article is sponsored by Coati Software. Written by me.

Intro  

The numbers come from link and link.

We can argue about the exact numbers, whether writing code is only 2 or 5% or maybe more. Or whether understanding code is 50 or 75%. But I completely agree that it requires X times more time to understand and read code than writing new parts.

Think about a new feature you add to your project. How do you approach such task?

For me it’s usually understanding the spec (or writing it), later, assuming I know most of the requirements I can start thinking about where to put a new code.

I am happy when I’m familiar with the area of the project where the new feature will be included. Still, even in a ‘known’ part of the system, I learn something new every time. So usually, I end up analysing the existing code.

Or imagine you’re thrown into an entirely new project. You sit in front of a huge code base… how to start and dig your way through?

What can we use to understand the code? Only a text editor? Maybe we can visualize the project?

The Tools  

What options do we have?

Of course, there’s your favourite IDE’s text editor. Assuming you’re not just using a Notepad, your editor will contain a few advanced features:

Basic tools  

  • Search - and a lot of its variations, like search in files, searching any symbols, etc.
  • Efficient navigation, moving between files, last visited locations, symbols.
  • Going to the definition/declaration of a method/class/name.
  • Finding (all) references of a symbol/name.
  • Listing all methods/types in a file/project.
  • And of course syntax colouring, seeing everything in black&white would be quite a nightmare.

Recently, it’s become quite common to include an extended version of a scrollbar (Code Map, Mini-Map). This is a little tool that allows you to look at a particular file from a larger distance and see its layout or places with changes/errors.

Ok… those are some essential elements. What other tools can we use?

With Visual Studio and some of its extensions (like Visual Assist), you can also easily navigate between hierarchies of classes. So you can know what a base class is, the chain of base classes, or what the derived types are.

Also, it’s great if you can navigate to related symbols: if you have a list of member variables, methods, constructors, etc.
Such a tool can significantly reduce the time needed to scan the source code where a type is declared.

Another useful tool is Call Hierarchy: to know where your function is called. It’s available in all Visual Studio versions: see a link here.

OK, but what else can we use?

Graphs  

Graphs!

It would be great to see the code as a graph of objects and their relations… something like a dynamic UML, where you can see the whole picture or some part of it.

And we have a few existing tools that can help us (and work with C++):

  • CppDepend - CppDepend offers a wide range of features. It is often described as a Swiss Army Knife for C and C++ developers. Offers Code analysis, Code Visualisation, Code Quality Metrics and much more.
  • SciTools Understand - very advanced. Understand is an IDE designed from the ground up to help you “Understand” your code. It can be used for maintaining existing code or writing new code from scratch.
  • Source Insight - a powerful project-oriented programming editor and code browser, with built-in analysis for large C/C++, C#, Objective-C++, Java programs, as well as other languages. Not only is Source Insight a great program editor, but it also can display reference trees, class inheritance diagrams, and call trees. (239$ per licence.)
  • Code Map from Visual Studio Enterprise.
  • Doxygen and other documenting tools that will also draw a ‘map’ of your code.
  • And: the hero of this article: Sourcetrail - a powerful tool for code visualization, multiplatform and independent from your IDE.

BTW:
If you like to have a look at this discussion at software engineering @Stack Exchange: How To Visualize Code? or C/C++ source code visualization? - Stack Overflow.

Sourcetrail  

What can Sourcetrail do for us?

First of all, it’s a tool that doesn’t try to replace your text editor. Its objective is to assist with code exploration by creating dynamic graphs that show your project from a different perspective.

When you work with code, you build a mental model of the relations between types. Sourcetrail helps with the task by drawing all the UML-like pictures for you.

Sourcetrail is built upon the three core concepts:

  • Code - the code around a selected type/name is shown, and at any time you can just read it as with other text editors.
  • Graph - interactive and dynamic graph built from the selected symbol name. It can centre around a class, file, macro, function… or even a template parameter.
  • Search and Navigation - a powerful search is required to find and navigate to a symbol quickly. Also, comes with autocompletion.

See below a default layout of the windows:

Of course, the trickiest part is the Graph.

But first, the short story behind the team and the product.

About the company, Coati Software  

Image taken from: their blog post.

Let’s first introduce the company behind Sourcetrail; the founders can share the fascinating story of why it all started.

Briefly, the tool was created out of frustration from working with large code bases (when Eberhard was working as an intern at Google). Reading only text is not the most efficient way of understanding a new code, so after a couple of experiments, the team started implementation of the project.

The full version of the story can be found on the following blog post:
Why working on Chrome made me develop a tool for reading source code.

The company are based in Salzburg/Austria.

Recently, at CppCon 2017, one of the founders of Sourcetrail, gave a little talk/demo. Just watch that short 4-minute talk:

Ok, but let’s move to the tool description!

Sourcetrail  

Some basic details:

Sourcetrail works offline, with all popular operating systems: Windows, Linux and MacOS.

Sourcetrail was in Beta from the spring of 2016 and has been available as a stable release since June 2017. Now, in Nov we have the version 2017.4.

What’s cool is that as of a few days ago (announced 25th Oct) Sourcetrail is now free for non-commercial use. So you can just download it and play! See more in this recent blog post: Sourcetrail 2017.4 – Sourcetrail Developer Blog.

It supports C++ and Java code bases. If you’re using CMake, it’s very easy to setup the compilation database. For Visual Studio, there’s a separate plugin that will do the hard work.

The team is very responsive to user feedback and open to feature suggestions. So have a look at this open bug tracker: github.com/SourcetrailBugTracker/issues. Suggest your ideas if you like!

Experimenting with the tool  

For my experiments, I’ve selected a project named Celero (v 2.1). It’s a microbenchmarking library (I wrote about it in this post).

It’s a project of a decent size. So it should be relatively quick to analyze and still see the tool operating on something more significant than a “hello world” application.

I wanted to go through the whole process of the setup and launching the tool. On Sourcetrail site there are example projects if you want just a brief look: sourcetrail/downloads - like clang source code. And in the tool installation image there some tutorials included as well.

Loading a project  

Before we can see some neat looking diagrams, we need to process the code.

Sourcetrail under the hood uses Clang tooling, so in other words, your code needs to be compiled under Clang. With the generated abstract syntax tree Sourcetrail can extract all of the details and build the desired code models.

It might be quite a hard task to setup everything, but Sourcetrail provides a lot of help here. In the case of Visual Studio, there’s an attached plugin that can help us: Sourcetrail Extension for Visual Studio.

Indexing  

After the project is set up correctly, you can load it into the app, and it will ask about indexing.

This process can take some time, depending on the project size, but usually you only have to do it once. Later cached data is used, so only changed files will be reparsed.

I’m not sure about the exact details, but although your code is compiled with Clang, not everything needs to be fully compiled. Even if you get some errors, the file will be indexed. (Except for fatal errors), see this issue for more info about error vs fatal.

BTW: I’ve also tried this on my big project, with 2 mln lines of code. I got many compilation errors, but only a few fatal in non-important files. Despite that, I could still browse the code and Sourcetrail worked fine with such a vast project.

Browsing  

Once the previous steps are completed, we can start looking at the diagrams.

Here’s what I get when I load the Celero project:

The above diagram is your home place. If you want to reset the chart, you can just click on the “Home” icon on the Search&Navigation toolbar.

Or you can also type “overview” (or some part of it) in the Search box.

Let’s now try to understand some code from Celero.

For example, after clicking randomly at nodes and classes, I’ve seen a lot of pimpl idiom used. There’s even a separate class for it:

When I click on the node class I get the following view:

What’s important here is that in a microsecond I get so much valuable information:

  • On the right hand there’s code of the class so that I can read it “normally”. For example, there are a few constructors and maybe it would great to update it to variadic templates :)
  • On the left, we see all of the relations:
    • member variables
    • template parameters
    • template specializations
    • referenced symbols

I mentioned that I clicked randomly on a node, but if you know what you’re looking for you can just type it, and a fuzzy-matching search box will quickly find it.

Sourcetrail works fine with nested types like Pimpl nested in the Archive class:

  • Blue nodes represent variables and fields
  • Yellow is for functions and methods

For example, when I click on filename I’ll see where the field is being used:

I’m impressed with this view! The blue lines on the diagram represent where a field is being used, plus we get a ‘snippet’ view in the source editor. That way I can immediately read the code in the relevant places.

In this view there’s “override” edge presented:

You can see where all of the implementations of Factory::Create methods are.

Also, I got one cool diagram. Have a look:

The picture above shows all the places where std::string is referenced.

  • yellow are all of the functions where string is used (also as an input params)
  • grey are the classes
  • red lines represent places where string is used as a template parameter

Perhaps, it’s not the most useful diagram, but it’s fun to see. Maybe that’s another good point of using this software (or other similar tools): you can just play with the code/architecture and have fun at the same time.

In this particular project, there is not much inheritance, and the class structure is pretty flat. But of course, Sourcetrail lets you see base classes and derived types. You can smoothly go up or down in a class family.

For browsing functions Sourcetrail presents call graphs: For example here’s one for function called Run() :

You can see both the caller side and the callee.

As you can see we can go over and over and browse more code. Let’s stop for now as I hope that little trip gave you a basic background behind Sourcetrail. There are so much more we can do.

So maybe you can just download Sourcetrail and see it for yourself?

Summary  

Strong points:

  • A powerful search
  • Nice looking diagrams/graphs… I mean really awesome looking!
  • Designed for C++/Java, but I think it will be possible to get support for other languages.
  • The initial indexing process might take a long time, but you have control of how many threads are invoked, you can even stop it and use only part of the information. Of course, there’s cache so only changed files have to be refreshed/reparsed.
    • I could for example run indexing in the background (by assigning only a few threads for the work), and still be able to work on my tasks so that Sourcetrail can finish its part.
  • Ready to use plugins (like for Visual Studio) to help you with importing projects into Sourcetrail.
  • Multiplatform: so works on Windows, Linux and MacOS.
  • Lightweight: it might fill a gap between no software for visualisation vs super advanced (and expensive) tools (like SciTools or SonarQube)
  • Useful tool for playing with templates - you can see specializations, parameters, etc.
  • Active development, new features every three months.

Plus:
It’s free for non-commercial uses :)

Weak points:

  • (general “problem” for such extra apps) Need to switch between tools. Although there’s an IDE helper that allows changing a bit faster, maybe it would be
    better to have the view entirely inside an IDE? Like a separate window next to your cpp file?
    • If switching is a “heavy” operation, then developers might be discouraged from runing the tool often.
  • Sometimes you might get a lot of clang errors, mainly if you use other compilers for your project (like Visual
    Studio). Still, even with errors, the symbol from the file appears in the graphs.
    • Track this issue to get more info about error vs fatal differences.

To be honest, I cannot find any more serious issues. I’m exploring the tool, and overall I am impressed. It works very well; the setup is easy to do, there’s a lot of help, beautiful and dynamic diagrams (even with smooth animations), under active development… what else would I want? :)

BTW: If you want to get the full commercial licence look at many discount options (see Sourcetrail Pricing): like 50% for freelancers and start-ups.

Or you can also take part in the giveaway to get a full licence, see below :)

Giveaway  

Together with Coati Software, we want to invite you to a new giveaway. You can get a commercial licence for Sourcetrail!

The Giveaway is closed now.