Understand 4 C++ Introduction

Not just another source code analyzer

During the last 3 years, I have been using a program called Understand 4 c++. It is made by a company out of St. George Utah called Scientific Toolworks. This product is their only piece of software as far as I know, but it is one of my favorites.

This product is a source code analyzer. It parses native code (version 2.0 does managed code too), and builds a database that contains all sorts of meta-data about your code. It doesn’t do lint style scrutinization out of the box, but it gives you all sorts of metrics about your code. For instance, this software can take a class, and tell you:

  1. Each place it was instantiated. This includes the file and line where it was used.
  2. How many methods the class has.
  3. The types of each method.
  4. If any member methods override a base class method.
  5. How many member variables the class has.
  6. A listing of base classes.

This same type of scrutinization can be extended to all types of ‘entities’ in the c/c++ language. For instance you can look at all sorts of meta-data associated with a function. For instance, given a function, you can determine:

  1. The number and type of it’s local variables.
  2. The type of return value of the function.
  3. How many local variables are declared in the body of the function.
  4. Which functions the function calls.
  5. Who calls this function.
  6. Etc..

API – Reflection for native code

Some of the features that are exposed in the UI of the product are limited compared to what the API exposes. The API is the closest thing there is to reflection for native code that I know of. Reflection for managed code is a really handy tool, that I’m sure C/C++ people have been wanting for a long time. But it only works for source code that is already compiled and that is currently executing. This tool allows you to statically ‘reflect’ over an arbitrary source code base. Powerful? Absolutely. I consider this tool indispensable when working with, and maintaining a huge source code base made of mostly native code. (I need to mention (again) that this tool and API also analyzes C# code too).

All this talk about the API, and I haven’t yet stated what languages the API is in. The API consists of one header file written in C. You need to combine this is with a help file that offers a list of entity types and reference types. If you don’t have the help file, the key to the API’s power will be forever locked to you. Anyways, they also offer a Perl API too. I wrote a lot of tools in the past targeting the perl API, but those tools are difficult to maintain due to perl’s complexities, and limitations.

The C API appears deceptively simple, and indeed it is. However the documentation is very basic and doesn’t explain a few important concepts. It looks presently as if it hasn’t been updated in years.

I therefore needed a better way to tap into the power of the API. Perl was out of the question: I was trying as fast as possible to forget any perl I ever knew. C was pretty low level, but not easy to work with. I wanted to write in C#!! But the makers of Understand 4 c++ didn’t offer a managed C# API. So what did I do?

I wrote a managed API myself.

A Managed API

During the previous year, I had learned to use C++ to write managed code for Microsoft .NET. Microsoft calls this language C++/CLI. So I took the Understand C API, and wrapped it in a C++ managed API that targets the Microsoft .NET framework.

After a few months of late night programming(And a long… Christmas vacation) , lots of frustrations, and lots of emails to product support, I finally got the managed API settled down to the point that it was usable. I wrote the whole thing in visual studio team developer edition, using unit tests. Doing so, I was able to achieve around 90% code coverage.

The end result was, that I can use C# to write my understand tools in. Sweet! I used that API to write some fun tools with. Eventually discovered a deep, obscure bug in the understand API. I reported it to them, and they promptly fixed it, and posted an update. (Chalk up one point for agile development practices, and a penalty for all other software makers who sit on their critical bug fixes for months on end). The people at Scientific Toolworks even did a light code review of the API. However, in the end, the entire project was mine, with no little to no input from anyone, except product support.

I currently plan on posting the managed API to the internet for free, in the hopes that someone will use it, benefit from it, and perhaps help make it better. The people at Scientific Tool works have also expressed an interest to post the API on one of their websites as well.

Example Code

Using the managed API, I am able to write code that looks like this. Here this method searches an array of methods, looking for a match based off of the symbolic method name.

private MethodType[] CompareFunctionNames(MethodType method, MethodType[] baseClassMethods)
	List result = new List();
	if (baseClassMethods != null)
		foreach (MethodType baseMethod in baseClassMethods)
			if (baseMethod.NameShort == method.NameShort)
	return result.ToArray();

This code below gets all methods from a class definition and iterates over each method searching for ones with no parameters.

private void ScrutinizeClassForFunctions(ClassType classEnt, FileEntity ownerFile)
	MethodType[] methods = classEnt.GetMethods();
	if (methods != null)
		foreach (MethodType method in methods)
			//Ignore Methods that have no parameters
			if ("()" != method.GetParameters(false))
				// Ignore the constructor and destructor methods since that is just noise!
				String constructorName = classEnt.NameShort;
				String destructorName = "~" + classEnt.NameShort;
				if ((method.NameShort != constructorName) && (method.NameShort != destructorName))
					// Check if the list of parent classes contains a function with a same name 
					// as the supplied function entity
					MethodSearchResult misMatches = FunctionMatch(method, classEnt, ownerFile);

So this API allows you to quickly and easily write custom tools to scrutinize and analyze your source code.

3 thoughts on “Understand 4 C++ Introduction

  1. Nathan Kidd

    I am extremely interested in using your .NET API for Understand (I am unfamiliar with Pearl). I tried to get the API from the Understand website, but they are moving their forums around and the post with your API downlod seems to be missing. Is there any way you could point me to where I might download and use your .NET Understand API?
    Best Regards,


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s