A Toolsmith’s Guide to the Understand API


Project toolsmiths write software that helps other software engineers on their projects better do their work. Using Understand’s C, Perl, and Python APIs to write programs about your programs, you can make your team more productive, smarter, and less dangerous.


Toolsmiths help make other programmers better

Today I noticed that a visitor to our website had come in from a GitHub page that linked to our website. Cool! I visited the page and learned that an enterprising programmer had used Understand’s Python API to write an extension to their bug tracking software that would analyze bug reports and predict what Java methods the investigating engineer might first explore for causes and solutions.

GitHub site for Understand script adding suggested methods for bug reports

The script used the API to find words in methods (names, comments, variables, so forth) and compute a frequency-inverse document frequency metric that associated words with methods. It then used that metric to recommend methods in the code as suggested starting places for investigation of the bug. Clever!

He was a toolsmith… writing tools to help his team fix bugs faster.

His script joins a long list (thousands) of tools written by toolsmiths at hundreds of customers.

Other examples include:

  • custom graphs highlighting changes to interfaces of classes and methods
  • custom graphs highlighting new logic
  • implementing / researching new ways of measuring code (metrics)
  • automatically building makefiles
  • adding style checks unique to the customers programming standard
  • automatically incorporating changes to code and creating new documentation
  • generating reports of how much a code body has changed by structure (new classes, deleted functions, so forth)
  • a custom GUI (using the C API) that automated a large gaming company’s software review flow
  • identify copy/pasted and duplicate code
  • determine the likelyhood that two bodies of code are the same with names changed

And thousands of more clever, useful, and specific uses for hundreds of different customers.

Types of Tools

The breadth of ideas our customers have for tools astounds me – we have smart customers! Their ideas generally divide up into these categories:

  • Enhancements to Understand’s GUI
    • Custom graphs These graphs can extend ones we provide already, or be completely new.
A custom call graph, via a Perl API script operating inside of Understand, shades functions by cyclomatic complexity.
Building custom graphs is easy!
Interactive Report widget showing the macro text expansion at that point in code.
CodeCheck – after running defect and style checks.
Running CodeChecks as part of a Jenkins CI process.
  • Lexeme / Lexical Analysis that dive into the contents of your source code with knowledge of what the parts are, and the text that makes up the code.
A simple Interactive Report that will run all API calls on each lexeme in a file
A script using the PERL API to follow calls and then build a graph clustering the calls by the file they are defined or declared in.

What will you build for your team?

The sky is the limit!

Need to know what code Bob worked on before he retired? A script will tell you. Need to sort out how many lines of code will be affected by a proposed change… a script will tell you that too.

How about sorting out what code uses a commercial library you licensed and now want to replace? Or a script that emails all changed classes, what changes they had, and who to talk to about the new interface? Yup.. you can do that too!

Or a Jenkins plugin that runs on every GIT check-in to ensure it doesn’t call forbidden functions? Or warning of new calls to sensitive functions like “fire missile” or “send money”?

Note that we are happy to help you learn the APIs and get your tools running. We may also have scripts already in our library that come close to what you need and might serve as a starting point.

Happy toolsmithing!

P.S. Please share your scripts and ideas with us. We love to hear of new uses for Understand’s API.