Build Notes

These instructions may vary slightly depending on your version of Windows, but in general the concept is the same.  I will register .cpp files for this example. When I’m done, whenever I double click on a C++ file, it will open in Understand by default.

First find a .cpp file in explorer, right click on it and select Open with –> Choose default Program

Click the Browse Button and navigate to the Understand executable, select it and click “Open”, by default it is at C:\Program Files\SciTools\bin\pc-win32\understand.exe

Understand will now show up in the list of programs available to open this file. Select Understand and make sure the checkbox is checked that says: “Always use the selected program to open this kind of file”. Then click ok

That’s it. Now Understand will handle those files everytime.

We’re excited about this new feature and would like your feedback, please let us know what you think or if you run into any problems.

More details

We are focusing the new forum on Understand 2.5 so are not migrating the content from the old forum. If you need to access old posts for some reason you can temporarily find them here.

You will need to create a new user account, and to prevent spam, all new user registrations are reviewed before you can post the first time. We apologize for the initial inconvenience but feel it will make the forum much more useable for everyone in the long run.

You can access the forum on the support page of the website, or here:

http://www.scitools.com/support/forum

Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior. Its heart is a series of small behavior preserving transformations. Each transformation (called a ‘refactoring’) does little, but a sequence of transformations can produce a significant restructuring. Since each refactoring is small, it’s less likely to go wrong. The system is also kept fully working after each small refactoring, reducing the chances that a system can get seriously broken during the restructuring.  — Martin Fowler  http://www.refactoring.com/

In other words, refactoring is making your code cleaner, safer, and easier to use. Understand can be a very powerful tool in your re-factoring arsenal. Here are a few ways you can use Understand in your refactoring process.

Quickly Identify References

In the long list of refactorings, many of the suggested refactorings involve replacing one data type with another. In many cases that can involve changing the calls to that data type as well. Understand can instantly show you everywhere that that entity is used, called, referenced, modified or typed. Just right click on the entity, select View Information, and expand the references section.

Identify Complex Functions

Many overly-complex functions can be refactored into smaller, more maintainable units. Knowing the McCabe Cyclomatic complexity can help you quickly identify functions and methods that are overly complicated and may be good candidates for refactoring. You can quickly find the complexity of every function in an Understand project by selecting Metrics –> Export Metrics. If you’re just looking for a quick list of complex functions, this plugin will show you the most complex functions in your project.

Download it from our Plugin page and you’ll see a list of the most complex functions in your project.

Reformat your code

If you have ugly code, you can beautify it quickly with the the tip reported in this entry:

Tip – Beautify your code

With one button press, turn a file that looks like this:

into this:

Rename Entities

Sometimes renaming an entity can go a long way towards making the code readable, perhaps a missed name class or method.

Download rename.zip for a user tool to quickly rename entities in Understand – it goes through the references and replaces each instance of the class or object with the new name.

Save the .pl script to your hard drive, and then in Understand under Tools | User Tools| Configure select Import to load the .ini file. Change the path to the location of the .pl file. Then to use it, right click on any entity in Understand and select User Tools | Rename. You’ll be prompted for the new text, and then all references to that entity will be renamed. You’ll want to reparse the changed files after each rename so that the database stays up to date (Ctrl+R by default).

Follow Dependencies

Understand’s new Dependency features can help you to quickly get a handle on what parts of the code are dependant on other parts of the code, letting you define what logical lines to divide your code into. Dependency Browser Dependency Graphs Exporting Dependencies

The short C/C++ example below shows how each line and statement contribute to these metrics in Understand. You can view the larger version here.

We have made a lot of changes to the licensing in Understand 2.5. How does this affect you?

1. These changes require a new license key.
2. All Understand features are now available to all users

As always, as long as your maintenance is up-to-date, there is no cost for the new version of Understand, we just need to generate a new license for you. The dialog that pops up when you start Understand has three options for getting that new license, whichever you choose, we will get the license to you quickly and without any hassle.

What if your maintenance is not current? You can still use any of these options, and we will get you a quote for getting back up-to-date. Also, the 2.5 install does not overwrite your previous version, so you can continue to use Understand 2.0 with your previous license.

We have a philosophy here that licensing should never get in the way of engineers using our tools. Over time this philosophy has resulted in many different experiments as we have tried to simplify licensing and added different ways for people to access Understand. As we prepared to release Understand 2.5 we realized there were now 36 different license types. As you might imagine that resulted in some very messy code, this feature is only available for these 16 license types, etc.

It was getting hard to maintain and we were seeing more and more licensing related issues. We decided to make a clean break, and created a new license that supports all features, thus bypassing the complicated licensing logic and we hope providing the best possible experience to our customers.

Abstract:

Recent studies have repeatedly found that smaller modules are proportionally more defect-prone. In this article, the authors formulate and test a hypothesis stating that smaller modules are proportionally more coupled, given that dependencies caused by coupling have been consistently associated with defect-proneness. Strong evidence supports this hypothesis. Furthermore, refactoring exacerbates this effect. On the basis of this study’s highly consistent results, the authors state the empirically based theory of relative dependency. That is, in large-scale software systems, smaller modules will be proportionally more dependent compared to larger ones. These findings have two implications for practice. First, we now have an empirically supported mechanism explaining the observations that defect concentration is higher in smaller modules. Practitioners can use this mechanism as evidence while seeking resources and support to revise or amend their organizations’ quality assurance and quality control practices. Second, particularly for the projects that refactor extensively, such as those using agile methods, focusing defect detection activities on smaller modules will increase their efficiency and effectiveness even more.

They used Understand to generate the C++ measurements of many large open source projects.  We donate licenses of Understand to worthy research projects frequently. We’ve e-mailed many times with Dr. Koru to support his efforts and are pleased his work was accepted by IEEE.

The team extensively used the DIT (Depth Inheritance Tree) and CBO (Coupling Between Objects) that Understand provides.

We’ve noted a few ideas for product enhancements from reading their article.

You will notice, however, that the Support Forum hasn’t been moved.  We’ve had trouble with it and our searching for a replacement.

It will come back on line, but not until we have a replacement we think we can stick with long term.

For now, use support@scitools.com or the Chat available on the website for support.

This weekend we released Understand 2.5 (build 507).  Its main changes include:

• Instant Search – a new feature which permits instant searching in even the largest bodies of code. Indexing starts after parsing ends. It operates in the background without holding up any other activities. When complete the search box in the upper right instantly answers your queries.
• Dependency Graphs -  these replace our old dependency graphs with new layout, saving, and cool clustering, save, undo, and redo options. They use a much updated layout engine, which we will roll into our other graphs and use to create new ones in the coming months.
• Simplified Licensing – Understand 2.5 includes all languages and all features. The only licensing difference, in terms of price, is the use of floating or specific developer licenses.  Understand 2.5 does use a new license – your old one will not run it permanently. Instead, it will operate for 30 days, giving you time to request a replacement license if you are under maintenance. This is done directly from Understand or via our website.
• Pricing -  we’ve removed all levels and language variants. Understand 2.5 has it all. This will be our path going forward with new features as well.  The new price is a little higher and the only differentiation is if you need a Single Developer or Floating License.   If you are under maintenance you can update to Understand 2.5 without any cost. Nor will the higher price affect your maintenance going forward. It will remain 18% of your purchase price annually.
• TrackBack Removed – this will be missed by many users, but we needed to focus on core analysis capabilities.
  Take heart, the engineer who wrote much of it will be taking it open source very soon. Look for an announcement here. To be notified by e-mail send a request to support@scitools.com.
• Menu Revamping – menus were moved about and standardized to be more in common with most applications. Additionally, edit menu items are now contextual with editor and graph operations. As an application ages, menus become complex and suffer from bloat. We wanted to simplify and reduce clutter.
• License Manager GUI with Improved Diagnostics – our old license manager does not need to be updated. If it is updated, or for new installations, a new License Manager GUI simplifies operation. Additionally, the server and clients have many more diagnostics embedded to diagnose any licensing manager problems.
• And many hundreds of bug fixes and minor improvements.

We know change can make winners and losers. We’ve tried to make every user a winner with Understand 2.5. If we failed for you, let us know how, and we will try to sort it out and make you as happy as we can.

I have written a .NET sdk wrapper around the understand API during the early spring and last fall. I wrote it because I didn’t want to use Perl anymore, and I wanted the strong type safety of .NET along with it’s wonderful debugging tools.
The API is written in managed C++ (i.e. C++/CLI), and once compiled, can be accessed by any programming language that targets the .NET framework.

More details at http://www.scitools.com/support/forum/viewtopic.php?p=5550

Thanks, Chris!

This is easy to do, and you can create your own User Tools to do many different things.

I went and bundled some CVS commands into a User Tool. Just import it via the Tools | Configure User Tools | Import button.

Download CVS User Tool

I haven’t used CVS in years, so let me know if I got anything wrong

For Input you can chose to use the selected text, the text of the entire current file, or not to use any input. You can output your results into the command output window like previous versions allowed, discard it, copy it to the clipboard, or overwrite the current selected text or file.

For example, the following would replace the word int with float in the currently highlighted text:

Yes, Find & Replace would do the same thing, it’s just an example

An example of replacing an entire file would be when using astyle to format your code. In that blog posting we had to overwrite the current file, and then reload it. Now we can feed the file text straight into the command and then the editor contents get automatically overwritten. No need to confirm the file reload every time:

As with many new Understand features, this was requested by a cutomer, we thought it was a good idea and that other people would use it, so we implemented it. If you have a good idea don’t hesitate to let us know. Just drop us an email at support@scitools.com

We are also in the process of adding Snapshot support for the Perl API for build 476. Now you can access historical versions of the code through your scripts as well. For example you can compare versions of files or write a script to compare metrics between versions.

What does this mean to you as an Understand script user?
In addition to the new features, the main side effect might be that some scripts might no longer work.

If any of your scripts stop working, review this list of incompatabilites in the Perl delta document. You can also make sure the scripts are still valid syntax by running maintain_uperl -c myscipt.pl.

The new snapshot changes modify the API in a few different ways:

• Db::snapshots() to get a list of snapshots for the db.
• $snapshot->name() to get the name of a snapshot and
• $snapshot->open() to open the snapshot and return a $db variable that represents the snapshot.
• The $db object is now “live”. It never used to be and it was never important that a script pass around and use the correct object. It is now critical.
• Entity objects carry with them knowledge of the database/snapshot they belong to. Multiple databases/snapshots can be open and you can have entities from them all at once.
• Any scripts which used entity ids $ent->id() as keys in hashes must be updated – the $ent->id is no longer unique across snapshots and multiple databases
  • At the beginning of the script add:   use Tie::RefHash;
  • declare the hash with:  tie my %my_hash, ‘Tie::RefHash’;
  • use the actual entity object as the key $my_hash{$ent}, not the dereference of the entity $my_hash{$ent->id}.
  • Don’t use Understand::ent->new($id) to reconstruct an Ent object from the id.

If you run into any problems that you need help with, feel free to post a question on the scripting forum, or shoot us an email at support@scitools.com

UPDATE- We found some issues with the above approach to $ent->id and changed it with build 477. Using a Tie::RefHash for entities does not work as intended and is no longer recommended. We added a new call $db->ent_from_id($id), to reconstruct entity objects from ids.  To use entities as hash keys without later retrieving the entities from keys, it is sufficient to simply use $ent for the key. To later retrieve an entity from a key, instead, use the entity id as the key ($ent->id()), and retrieve the entity from the key with $db->ent_from_id($key). Note, it is not possible to safely store entities from different db’s into the same hash using this technique, since id’s are not unique across multiple open db’s.

We’ve had dependency analysis in Understand for many years.  With B471 of Understand 2.0 we have consolidated it into a functional area of the tool, improved what it does and also added a few new dependency views.

The Dependency Analysis capability provides these features:

• rapid browsing of dependencies for files and Understand architectures
• Dependents, Depends On, and Butterfly graphs for files and architectures
• Spreadsheet export of dependency relationships
• A new Dependency Browsing dock that shows all depedency information

Read on to learn more about the Dependency Analysis capability and what we plan for it.

Or watch the video here.

Lots of Data

To calculate dependency we have to examine every refererence in an Understand project. We then build up dependency data structures for every file and architecture. This includes the nature of the dependency and the references that caused the depedency.

Because this can be a lot of data, we don’t calculate this as you ask for a given dependency relationship. Instead, we calculate all dependency information, cache it, and this makes subsquent exploration and browsing quick.

So the first step is to tell Understand you want to explore dependency information, by choosing:

Note the Scitools Labs icon next to the menu. This means this is an early feature, so don’t depend on it and also send feedback if you have ideas about it.

Depending on the size of the project building this cache can take a while. On 2 million lines of code, it will take about 15 seconds, but the time will depend on the reference density of the code.

After reparsing the cache will still be used, you currently have to remember to update it, although in a build or two we will ask if you want to update it.

Exploring Dependencies

Once the cache is created, you can now explore dependencies using the Dependency Browser. To get it, right click on a file or an architecture and choose “View Dependencies”

The Dependency Browser then pops up, by default docked to the right side of the interface.

The browser shows that “adler32.c” depends on two other files (zconf.h and zlib.h).  Clicking on zconf.h shows the references that caused the dependence.   It also shows that adler.c is depended on by 3 files, to see them click on the tab.  Note that these references are hot, click on them to visit the source location.

The [x] Sync button at the top tells Understand to show dependency information for whatever entity you click on elsewhere in the interface.

Dependence Graphs

We provide, currently, three graphs for files and architectures:

• Dependency Graph – edges show that node a depends on node b
• Reverse Dependency Graph – edges show that node a is depended on by node b
• ButterFly  – shows dependence and dependency

To get a graph, just right click on the file or node in question, or choose the graph icon in the Dependency Browser:

Choosing the Dependency Graph for adler.c we get:

Adler.c depends on zlib.h twice in the code, and 4 times on zconf.h, and so on.

Data Export

You can export relationship information for a file or architecture to CSV format by clicking on the  icon. This will do output dependency relationships in matrix form for that entity. 

You can also get the matrix for all files or architectures by choosing the CSV export options from the main Dependency menu:

Our Intentions

We want your feedback on these features – both in how we implement them and also what else we should do.

Our plans currently include:

• Dependency information for Java, C#, C++ Classes  & Ada Packages
• Dependency Rules – a specification system indicating permited and non-permitted dependencies
• Dependency Corrections – system for correcting false positives dependencies
• Access to Dependency Information from the C++ and PERL APIs