Imagix 4D User Guide


Components and Terminology

Checklist

A checklist is set of checks that reflect the set of rules constituting a given standard or guideline. Checklists are a project-independent resources from which the specific checks for a given project / review are selected.

Standards include:

  1. rules that can be checked fully and automatically by static analysis tools
  2. rules where violations can only be found through inspections by programmers
  3. rules that require checking by dynamic analysis tools
  4. rules that ask for descriptions of aspects of the software environment
  5. rules that don't apply to C, C++ or Java source code

The Review Tool supports the review of these rules at two levels. First, it significantly improves productivity in checking those rules that are typically most time consuming. It guides and automates as much of the manual inspections (2) as possible, and performs some of the automated static analysis tests (1).

Second, it supports the overall process. The Review Tool serves as a single, cohesive repository supporting the documenting, tracking, reporting and auditing of review activities for all categories of rules. For instance, the tool can record the results of external analysis tools, integrating those within the overall review document.

In addition to checklists for initiative standards, the Review Tool supports checklists for generally accepted design practices. The Imagix-Checks checklist can be used to identify, assess and document parts of your software where Imagix 4D's metrics, source checks and flow check reports indicate potential design or implementation problems.

Review

A review is a set of checks against which the software in an Imagix 4D project is evaluated.

A review is specific to an Imagix 4D project. A review can include checks from different checklists, and a project can have multiple reviews.

Within the review, project-specific data is collected and recorded about each check. During the review process, this underlying data grows. Backups of the review are created automatically and manually, and can later be used to restore a previous point, or to compare review changes between two points.

Check

A check is a description of a certain style or behavior of the software that is a potential concern for correctness, consistency, compliance, performance, security or other desired property of the software, together with a set of ordered actions which lead to the identification and assessment of those portions of your software tied to a specific rule in a standard. There is typically a direct correspondence between the rule in a standard and the check in the Review Tool.

A check is identified by a unique name within a checklist or review.

The checks have been designed to minimize the manual work necessary to conduct a review. This is partly achieved by creating common steps that can be shared between checks, and separating these steps into preparatory checks; the results of these checks can be shared as downstream inputs among multiple checks. Such preparatory checks are identified through their names, Prep-xxx.

A second category of checks are those that contain just documentation about the checklist or the use of Review Tool. These are identified by their Info-xxx names.

Typically, all other checks in a checklist, and in a review, correspond to specific rules in the standard. Each such check has a unique name, associated with the rule from the standard. Sometimes, a set of related checks when combined together ensure conformance with another check, or rule. In these cases, the composite check is still listed in the review and checklist, but when it appears in the Review Tool, the Check display indicates the individual checks that make it up. This helps structuring the review process by imposing a hierarchy to a checklist.

Step

A step is a specific action in identifying or assessing some portions of your software. Each check is made up of an ordered list of such steps.

The Review Tool implements a set of specific action types, and these are used to define steps. Some of these action types involve an analysis based on a set of input probes, and generate a set of output probes. Steps employing these action types can generally be automated. Even when the output probes are automatically generated, they can be manually overridden.

Other action types require the reviewer to apply their knowledge and analysis of the software to manually identify symbols (functions, variables or datatypes) or lines in a source file that conform to the criteria described in the step. Typically this is done by using Imagix 4D's general visualization and analysis functionality. Alternatively, for steps where the criteria are related to standard language features or libraries, step-specific standard probes files can be loaded to identify candidate symbols.

Probe

A probe is an artifact tied a specific portion of your software.

There are several types of these. Probes can identify particular symbols in your software (functions, variables, macros, and data types), particular locations in your source code (source file and line number(s)), or particular locations together with related symbols (such as variables being read in a statement). This last type of probes is typically generated by automatic steps, such as by running the variable flow check analysis, but can also be added manually by the user.

Because probes can serve as inputs to other steps, some probes involve specifying Imagix 4D settings that are used to run analysis. This is specifically the case for Critical Region definitions, where the definitions are recorded as a probe, and then used as an input for running a task flow check analysis as part of a downstream check.

To enable full flexibility in identifying and tracking anything in the review process, notes can serve directly as probes (in addition to being attached to probes). For instance, this provides a way to record the results found by an external static or dynamic analysis tools.

Rating

A rating is an assessment of whether a given probe is in conformance with the rule being evaluated. The final step in each non-preparatory or informational check identifies the probes directly related to the rule being reviewed. It is these probes that are assigned a rating.

Each probe can be assigned a rating of No Issue (ok), Concern, or Violation. Probes can also be set as Unrated (their initial condition).

Another action that can be performed on a probe is to remove it from a step. This has an impact different from assigning a rating of No Issue. A No Issue rating indicates that the probe has been identified, inspected, and found not to be an issue. Removing a probe erases any record that the inspection took place, and leaves no artifact on which to base reviews of later versions of the software. Therefore, probes in final steps should be rated, rather than removed, unless they simply do not apply to the rule being checked. However, in earlier steps that are based on user input, removing incorrectly identified probes is useful, particularly in avoiding the propagation of the incorrect probes to downstream steps.

Note

A note is a text string associated with a review, check, step or probe. Notes provide the ability to annotate and comment on artifacts and therefore add to the document record being built up.

Many of the actions involved in conducting a review automatically generate a note, aiding tracking and audit activities. In addition, menu items enable you to create and attach notes to most items (review, check, step or probe) throughout the review process. These notes remain as a permanent part of the review, unless removed. When multiple notes are attached to the same item, they must be removed in order, with the most recent note removed first.