Best Practices for Creating User-Defined Coding Standards

User-defined coding standards defined using the Polyspace Query Language (PQL) have a hierarchical structure. You can split a coding standard into multiple components placed in separate folders and then assemble the coding standard by using their hierarchical relationship. Using a modular approach can make maintenance and further development easier.

Organize Files for Components in Separate Folders

A user-defined coding standard is a hierarchical document. The coding standard is contained in a catalog component. This component contains one or more section component, which in turn contains one or more rule component. When organizing the source files for a user-defined coding standard, keep files of different components in separate folders:

At the start of development, create a dedicated folder to keep the coding standard. in this folder, at the command line enter:
```
polyspace-query-language init
```
This command creates the file main.pql and places the necessary code to compile the coding standard. Avoid manually creating main.pql.
Place related sections in their own folders. For example, if your coding standard myStandard has four sections Syntax, Naming, and Loop Style and Function Style, declare each section in their own .pql file and organize the files like this:
Declare the sections in their own packages. Place the content of each folder in their own packages:

It is good practice to use the same name for a package and the folder in which it is declared.
Define the rules in separate .pql file in the folder corresponding to their section. For example, define the rules of the section Naming in the folder myStandard/Naming in separate .pql files.
Define components such as sections, rules, and catalogs in the package corresponding to their folder using the package keyword. For example, for the rules and sections in the Style folder, start the .pql files with this package declaration:
```
package Naming
```
Use consistent naming patterns and naming style for your components.
Use attributed such as Description, Id, Category, and Subset to annotate your components. Annotated components make your code easier to read and maintain. Using explanatory and descriptive annotations can also make results review simpler.
Avoid monolithic organization. Define the components of a coding standard in separate folder and packages. Then, in the file main.pql, assemble the defined components. For example, define the coding standard myStandard in myStandard/main.pql like this:
```
package main
// Attribute annotations...
catalog myStandard = {
  Syntax.SyntaxRules,
  Naming.NamingRules,
  Style.LoopStyleRules,
  Style.FunctionStyleRules
}
```

Arrange Rules in Sections and Subsets

A user defined coding standard is a collection of rules from supported coding rules such as MISRA C/C++ standards, AUTOSAR C++14, and Bug Finder defects. For easier use, follows these guidelines when arranging the rules in the coding standard:

Avoid monolithic organization. Arrange similar rules into separate sections.
Annotations like Description allow you to specify how the sections are labeled in Polyspace user interface. Use appropriate annotations for easier results review.
In the Polyspace user interface, you can select rules with the same Category attribute by using a single click. Sort the rules of your coding standard in separate categories by using the Category attribute.
The Subset attribute is also selectable in the Polyspace user interface. Using Category and Subset, you can organize your coding rules along independent logical axes. For instance, you can divide rules into category based on their overall importance. At the same time, you can divide rules in to subsets based on the stage of development at which they are relevant.
Specify a consistent label for the rules using the Id attribute. This attribute is used for justifying violations of your coding rule. Use Id that are logical and easy to remember.

Update Components

If you follow the best practices for developing user-defined coding standards and coding rules, the coding standards and coding rules are modular. To update a coding standard, you need to update only the affected component. You can add or remove a section, add or remove a rule, or update a rule.

Add or update sections

You can add a section as part of a new package or an existing package:

To add a section as part of a new package, create a new child folder under the folder that contains main.pql. Alternatively, navigate to the folder corresponding to the package in which you want to add the section.
In a new .pql file, declare the section component. Place the component in the package corresponding to the folder in which you placed the .pql file.
Specify the new section in the catalog component in main.pql.

To update the attribute or rules of an existing section, navigate to the folder corresponding to the package of the section. Locate the .pql in which the section is defined. You can update the section by modifying only this source file.

To remove a section, simply remove the corresponding section declaration from main.pql. Optionally, you can also remove the folder corresponding to the section.

Add or update rules

To add a new rule to a section, navigate to the folder containing the section. Define a new rule in a new .pql file, specifying the package corresponding to the folder. In this file, define the rule component by mapping to an existing checker or by creating a new defect component. Finally, add the rule to the section.

To update a rule, locate the pql file in which you define the rule and then make necessary adjustment.