Introduction to VeriPrism Structured Comments (VSC)

A simple, developer focused tool for connecting information.

As we developed experience using other tools, we realized that there was information that we were missing in just source code DNA. We were missing some context that would help frame the way the software was used in a way that would increase the architects understanding.  We also realized that the mechanism to do that was not yet another application, but to extend the analysis of VeriPrism.

VeriPrism Structured Comments (VSC) are a way to facilitate that process without adding more overhead to the application teams. Once implemented, a whole new perspective can be added in.

How does it work ?

Most Languages have a comment directive. Its considered good form to comment the code as it is written to make sure that people working on it later understand what the design decisions were. But in looking at thousands of programs, this isn’t done enough and when it is done, it becomes stale. We wanted to make the lowly comment an active player in the software landscape.

VSCs are specialized “tags” that can be added to any line or block comment structure. Comment lines vary by language but because we are actually looking at the “DNA” of the comment, its very easy to pick out. Using Python as an example, generally, comments will look something like this:

# This is a comment

Where the  # is followed by a white space. To turn this into a VSC, simply add a ‘!VSC’ anywhere in the line.

# This is a comment !VSC directive data

Where ‘directive’ is a VSC command, and ‘data’ is a value (or set of values). For example, suppose the developer wanted to make sure that the architect understands that this module will be deprecated in the future. The VSC command is “lifecycle” and the values in this case is “harvest”. This tells the developers not to fix any of the defects in this module unless they are critical and that it will be replaced. 

# This is a comment !VSC lifecycle harvest

This will appear in the definition of the module as lifecycle harvest and become part of the analysis.

This example is simple, but what about some more complicated choices. Lets consider a message broker architecture.

#!VSC message new_app_broker

The “message” command tells our database to connect this module with another application (new_app_broker) visually. Now when the structure is displayed, the connection arrow will jump from this application, to the other application. It can even be directed to both the main node, and/or subnodes.

#!VSC message new_app_broker DAO

This will connect the root nodes, as well as connect this to the DAO object in the other application.

It is that simple.

VSC COMMANDVARIABLE(S)PURPOSE
Software Bill of Materials
companycompany nameThe name of the company which authored this code
authornameThe name of the person who wrote this code. Separate multiple names with commas
hashvalueHash value for the module as delivered. Should match the developers’ hash.
sourcelocation/urlSource location for the code. Can be a URL.
licenselicense typeName of the license type (e.g. MIT)
datedateDate this information was updated in the form yyyy/mm/dd
fingerprintfingerprintdataThe official standards fingerprint to avoid lookups
Message Broker
messagetarget_program
target_module
Connects this callableUnit to the target_program and the callableunit:target_module. If this is a message broker (e.g. mulesoft) then just use the target program.
datatransfertarget_program [variables]The variables stored as a list [,,,]. Each one will be found in the current compileunit and the definitions connect to the target program.
priorityvalueOccasionally disaster planning requires that the interface also have a restoration priority.
Work In Progress (WIP)
WIPnoneWIP indicates that the code in this “branch” should not be scanned for defects. It will be scanned for sizing but any defects will not be stored in the scoring. A punch file will be created but if it is WIP it is assumed to be under major development.
(note: admin can override this command for inspection)
Information
vendorvendornameVendor, if any, responsible for this code – not used on code maintained in house
lifecyclecyclephaseapplies to whole application; intends to give guidance to testing teams
ownernamename of application owner within the organization
emailowners_emailowners email
organizationorg_namename of the organization with responsibility for this application
complexity1 – 10complexity rating heuristic
userbasenumbernumber of end users
disasterrank1 = low priority restore, 10=high Priority restore
exposureinternal/externalIndicates if the app is exposed to the public ( so security errors get very critical) or internal only ( important but not critical)