Cooperating in SciTools Understand through Annotations


Version of Document: V1.0
Author: Stephane Raynaud, Emenda USA (Stephane.Raynaud@Emenda.com)
Tested with Version 4.0 of SciTools Understand ( Build 867 )

1. Objectives

Cooperating during Peer Code Review.
Husband writes code.
Wife: Honey, please got to the super market and get 1 bottle of milk. If they have bananas, bring 6.
He came back with 6 bottles of milk.
Wife: Why the hell did you buy 6 bottoles of mile?!?!
Husband ( confused ): BECAUSE THEY HAD BANANAS.
He still doesn't understand why his wife yelled at hime since he did exactly as she told him.
The Importance of "Communication" when talking to a "Coder" ( credit: Fluid Studios )
When two developers want to share ideas around a piece of code, it is often difficult for them to collaborate effectively as soon as they are not in the same office. Also, while developers are reviewing code they often want to look at code in a place where they will also be able to investigate, drill down (in classes, files or functions) and freely run with their thoughts.
Reviews may be live conversations but may require a step by step conversation occurring over different schedules or even time zones (if one of the developers is in a different time zone). We solve this issue by playing scrabble with overseas friends in "Words with Friends", each of us playing in our own time zone, but can we do the same with code?
If you've ever met me and attended one of my seminars you are already convinced that SciTools Understand is a unique place that lets developers investigate, understand and modify code.
While SciTools Understand helps you (you as a self-contained engineer), can SciTools Understand help you cooperate? Or do you need to buy a complex and expensive infrastructure instead? Do you really need to set up a central server that some solutions require, or can you use what you have already?
Can you simply use what you have, i.e. a shared drive, a nfs folder or the Cloud (Hint! Hint!)? ...
Yes, SciTools Understand can help you and I am going to show you how!

2. An Understand File per developer

I recently asked a customer: "what do you do for code review?", "what do you give the developer?". The answer was "We give him the code and a specification document...".
Our advice is to also provide your developers with a copy of a .udb file, each one having their own copy running on their desktop.
But what's a udb file? It is the file created by SciTools Understand when you run an analysis. The .udb file (and the source code) is all you need to fully use a SciTools Understand Analysis.
Can I really share udb files? Yes, they are standalone, so you can move them around, copy them, share them and even put them in your SCM!
But the source code is not at the same location on every machine? This is easily solvable by using portability to specify a named root, if you don't know about that yet , there is a "Hint" at the end of this paragraph.
BEST PRACTICE: Integrate the creation of the Understand file in your build process.
It is possible to include a copy of the .udb with your code release distribution. Every developer will be able to use it. You can create the .udb file manually with each build or you can fully automate its creation through scripting or you can reuse an existing version and re-run the analysis by using "und analyze -db <YOUR_UDB_FILE>". If you are not sure how to do this, send me an email or contact Emenda.
Is this it? I put the .udb file on the share drive and now 2 people can use it and start cooperating? Well... not really... it would be too easy, wouldn't it? If you were to do that, your second developer will be out of luck and will be getting frustrating messages of "your file is locked"...
Failed Save
You can "distribute" udb file copies, but you cannot "Share" a single copy
This is usually the first way people try to collaborate with Understand. Some have tried and stopped here... However, don't worry, this isn't another marketing white paper, in which after 15 min of reading, you realize it was fluff with no real resolution... The solution is in annotations!!! Let's jump to the next paragraph, unless you don't know how to use Portability to specify an Named Root...
Hint: Using a Named Root for Portability in SciTools Understand
It is always a good idea to use named root when creating udb files. It provides better portability between developers (they don't all have their source code at the same place). Named Root lets you define an "environment variable" that defines the ROOT of your project.
a) Open your project settings in SciTools Understand (Project->Configure Project)
(Alternatively, you can do this when you create the projects and add files to it)
b) Select Files
Select files
c) On the right of the window, click "Portability"
Select portability
d) Select "NamedRoot"
Select named roots
e) Lastly, add a "Named Root" using the "Edit Named Roots..." button on the bottom left. In my example, I define a LIBFREENECT2_ROOT for the root of my project, and it points to C:\Users\steph_000\Desktop\DEMOS\SonarQube\demo_project\libfreenect2-master.
Create named root
SUPER IMPORTANT: If you use a .udb with Named Roots in the command line (outside the GUI), you must add the UND_NAMED_ROOT_ in front of your named root name to define the equivalent O/S Environment variable. In my case, I would need to define the following environment variable: UND_NAMED_ROOT_LIBFREENECT2_ROOT for a named root that is LIBFREENECT2_ROOT in the GUI.

3. Using Annotations in SciTools Understand ( Single User )

Annotations in SciTools Understand understand are saved in an .ANN files. In fact, .ANN files are a SQLite database... And because it's SQLite they don't lock up! Also, they are not included in the udb file! This seems like what we are looking for!. But before we look at this, let's learn first about Annotations and how to use them.
You can have multiple annotation files in the same .udb project. They can be found using:
Annotations > Annotations Options
Or you can simply find them in your project settings:
Open annotations
The Annotations Files
When you go through the code, you can annotate files, classes, functions, or lines...
Simply right click anywhere on the code, and you can annotate whatever is under the cursor. In most cases, you must choose if you want to allocate the file, the "entity" or the line number. (It's only confusing in case of a constructor, because both the class and the constructor have the same name...).
NOTE: Annotations are not in the code. They are not 'lint lines.' They are also smart. They are tied to an entity (unless you tied them up to a line...) so if some of the lines are changed the annotations will still appear on the entity!
Right-click annotations context menu
The Annotation Context Menu
Sample annotation
The Resulting Annotation
Simple, right? Before we configure this for cooperation in the next paragraph, I want to share a few helpful tips:
Hint: Create Keyboard Shortcuts
The Annotation menu is not always practical (it's matter of taste, so you may like it...), but I prefer to define "Key Shortcuts" to create and refresh annotations.
To do so, go to:
Tools > Options
then select
Key Bindings
In the key bindings, search for "Annot" (as in Annotations) as shown here:
Annotation keybindings
I will suggest Creating a Shortcut for "Annotate Current Line", "Annotate Selected Entity" and "Refresh Annotation". By default, all those are not set to anything.
Also,
Hint: Use tags to find annotations easily
When Creating an annotation, you can use the # keyword to add a #tag or a #tag:value pair. This is useful in a complex environment when retrieving annotations pertinent to a specific bug or issue.
Add an annotation
Adding a "Tag" for Bug 3344
As discussed, it will be useful to "search" for all the annotation related to Bug 3344:
Find annotation
Searching for all annotations related to BUG=3344
You can also search by "Date and Time".

4. Putting it all together to "Cooperate"

I am sure you have figured it out already, the solution here is to simply put the .ANN file on a shared drive or a nfs drive or the "Cloud"...
Select annotation file
The annotation file can be on the network
The only downside is that annotations are not refreshed automatically when the database is updated by a user. I will be contacting SciTools in a near future and see if they can include an automatic refresh of the annotation. A lot of users have found that adding a keyboard shortcut to a "Refresh Annotation" is the best way to deal with this limitation.

5. Configuration & Best Practice Examples

We are done! However, I wanted to also share a few ideas on how .UDB and .ANN can be used in your organization to help developers cooperated internally, but also externally.
5.1. Create a universal UDB for your project and share it with every developer
Create universal .udb
Best Practice: Create and Share a UDB File with your developers:
This is the first step in cooperating with annotations.
5.2. Share "Global" Annotations file on the "private Cloud"
Share master annotations
Sharing an .ANN file globally as READ/WRITE (Cooperation) or as READ-ONLY (Tips, Hints, Technical Debt)
5.3. A Developer can share his/her annotation file with others
Individuals share annotations
Sharing for Code Review
5.4. A Developer can EMAIL his/her annotation file to others
Email annotations
Emailing Your Annotation File
5.5. Annotation file can be code generated from other tools and shared.
Automatically generate annotations
Looking at the output of "Tools" directly in the code by storing their output in Annotation Files.
Wouldn't it be nice to have the result of "Code Check" in an Annotation File?
5.6. If you provide a programming API to your customer, annotations can provide API "Hints" to them, within your code. They can be changed without changing the code.
Use an API to create annotations
Providing .UDB and .ANN file as documentation to your API Client.
Could it also be a good idea to request it from your supplier?

6. About the Author: Thanks for Reading.

Stephane signature
Stephane Raynaud, Principal at Emenda USA. Stephane is an engineer that decided to pursue a career in software development and consulting. His first job was developing requirements for a drone program and prior to Emenda he had been running a multi million dollar consulting organization around C and C++. He is now applying his expertise and Emenda Best Practices to help software developers across North America build better code. ( Stephane.Raynaud@Emenda.com )