Best Practice for Defining User-Defined Defect Checkers

User-defined defect checkers are logical combinations of predicates from Polyspace^® Query Language (PQL) classes. To detect a defect, you can design a defect in multiple ways but not all design choices result in checkers that are faster and easier to maintain. This topic describes the design best practices that can result in faster user-defined defect checkers that are easier to maintain and debug.

When developing user-defined coding rules:

• Develop each rule in its own .pql source file. Keep the file in the folder corresponding to the section in which you want to place the rule.

• Specify the package in which the rule belongs. That is, specify a package at the beginning of the .pql file.

• Avoid creating complex queries. Break complex queries into smaller user-defined predicates. This approach allows you to reuse the predicates in other rules and makes the rule easier to understand.

• Specify a message string that explains the defect that the rule checks. Construct messages that include the name of the object being flagged.

Keep Checkers Modular

Similar to a user-defined coding standard, developing the user-defined defect checkers in a modular way results in easier maintenance:

• Separate the defects in their own .pql file — In a coding standard, a defect is part of a coding rule. Following the best practices for coding standards, you can store rules for individual sections as part of a single package and therefore a single folder. Keep the rules in their own .pql files in this folder. Keeping defects in their own folder makes it easier to test the defect in isolation in a unit test. If you use a continuous integration workflow, you can submit the defect, corresponding test C/C++ code as well as a unit test for the rule all together.

• Build defect checkers using smaller user-defined predicates — Avoid implementing defect checkers as a monolithic and complex combination of PQL predicates. Because PQL is a declarative language, you cannot step through a monolithic coding rule and find the points of failure as you would in C/C++. By developing the defect checkers by using smaller predicates, you can test the predicates individually and identify the points of failure. For an example of this workflow, see Detect Semantic Issues Using Polyspace Query Language Semantic Classes.

Use Semantic Classes When Possible

The Polyspace Query Language (PQL) supports two kinds of classes — Syntactic classes and Semantic classes. For an overview of these classes, see:

• Overview of Syntactic Classes in Polyspace Query Language

• Overview of Semantic Classes in Polyspace Query Language

If the issue you want to detect can be detected by using the semantic classes, use the semantic classes instead of syntax classes. The predicates of the semantic classes have access to fewer aspects of your code and as a result are generally faster. The syntax classes model the syntax tree of your code. These classes require handing larger amount of data and can be slower.

Use Syntax Classes with Care

The syntax classes query the syntax tree of your code, which is likely to be large. Each predicate of the syntax classes queries this large database and the retrieved information can also be very large. You can speed up the Polyspace analysis while detecting a syntactic issue by following these best practices:

• Avoid querying for generic syntax elements — When querying the abstract syntax tree of your code, query for specific nodes like IfStatement, TypeDeclarator, or LambdaExpression. Avoid querying for generic nodes like Node or Identifier. The data retrieved by a query for such generic nodes can be very large and slow down the analysis significantly.

• Avoid logical operations involving generic syntax element — In PQL, each predicate retrieves a data structure. A logical operation on a predicate performs the logical operation on or between these data structures. If the data structures are very large, logical operation involving the data structures can be slow.

• Only negate boolean predicates — Syntax classes contains boolean predicates that are intended to be used with negation operation. Avoid using nonboolean predicates in negation operation.

For an example of a syntactic defect checker that follows these principles, see Detect Syntactic Issues Using Polyspace Query Language Syntactic Classes