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.
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 COMMAND | VARIABLE(S) | PURPOSE |
|---|---|---|
| company | company name | The name of the company which authored this code |
| author | name | The name of the person who wrote this code. Separate multiple names with commas |
| hash | value | Hash value for the module as delivered. Should match the developers’ hash. |
| source | location/url | Source location for the code. Can be a URL. |
| license | license type | Name of the license type (e.g. MIT) |
| date | date | Date this information was updated in the form yyyy/mm/dd |
| fingerprint | fingerprintdata | The official standards fingerprint to avoid lookups |
| message | target_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. |
| datatransfer | target_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. |
| priority | value | Occasionally disaster planning requires that the interface also have a restoration priority. |
| WIP | none | WIP 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) |
| vendor | vendorname | Vendor, if any, responsible for this code – not used on code maintained in house |
| lifecycle | cyclephase | applies to whole application; intends to give guidance to testing teams |
| owner | name | name of application owner within the organization |
| owners_email | owners email | |
| organization | org_name | name of the organization with responsibility for this application |
| complexity | 1 – 10 | complexity rating heuristic |
| userbase | number | number of end users |
| disaster | rank | 1 = low priority restore, 10=high Priority restore |
| exposure | internal/external | Indicates if the app is exposed to the public ( so security errors get very critical) or internal only ( important but not critical) |
© 2020 VeriPrism LLC – VeriPrism, Application DNA, and Intelligent Sizing Units are Trademarks of VeriPrism LLC
