polyglot-tools-docs

Overview

explorer sample

TL;DR: If you don't want to read all this, jump in and have a play with the Polyglot Code Explorer or another sample with multiple codebases

I've also recently written an introduction to these tools on my blog - and talked about them on the ThoughtWorks tech podcast.

I've recently added an updates and news page here


The source code is on GitHub:

I should add a disclaimer - this is a side project of mine, and is far from perfect! Full disclaimer and a bit more background here.

What are the Polyglot Code Tools?

These are a bunch of tools I've been building in bits and pieces over the past few years, in an attempt to answer the question:

How can we visualise large codebases without needing complex language-specific parsers and logic?

Why visualisation?

I'm a visual thinker, so my main focus is on visualisation - especially when trying to spot patterns in millions of lines of code.

It is far quicker for me to look at a diagram and see some unusual colouring in one area, than to see the same information in a table of numbers.

Why polyglot?

Polyglot means "speaking multiple languages" - in this case, it means these tools should work, to some degree, for any text-based programming language.

I've worked in many programming languages over the years, and many of them don't have good or easy code quality tools - either they are too new for a community to have built them, or they are from ancient projects where even if such tools exist, getting them up and running is a headache. And each tool probably produces different metrics in different formats - it's hard to get any sort of big-picture view.

Also many real-world systems don't use a single language - often it is better to use specialist languages for different tasks, rather than one general-purpose one. For example one project might have a UI built in JavaScript and HTML, a microservice built in Kotlin and a platform automation tool build in Rust.

Where did this come from?

The basic ideas came from Erik Dörnenberg's articles on Toxic code visualisation plus Adam Tornhill's book "Your code as a crime scene" (Tornhill 2015) - plus a lot of research that Adam's book lead me to.

See also History for more about how this all started.

The Polyglot Code Explorer

I talk about "tools" here, but at the moment there is really one main application, the Polyglot Code Explorer - which is the front-end component of three tightly coupled applications:

Tools flowchart

You use the Polyglot Code Scanner to scan your source code and produce a data file, then the Polyglot Code Offline Layout tool to add layout information to the data file, and finally the Polyglot Code Explorer to view it in a browser.

There is also now also the Simple Code Server which the explorer can use to let you view source code inside the explorer.

For an overview of how to actually use these apps, look at the Explorer How To page.

You can see a demo of the explorer in action at http://polyglot-code-explorer.s3-website.eu-west-2.amazonaws.com/ (this might not quite match these docs, as I sometimes use it as a playground).

Git Logging Tools

I actually realise I haven't pushed these to github yet! Which is good as I don't really need to document them :) Just suffice to say, I have some work in progress for trying to get yet another git log visualisation thingy working. One day. But the explorer has taken priority for now.

There's an older example of this at https://github.com/kornysietsma/git-cd-chart-twuk2018

Edit this page on GitHub