Detect Misaligned Multiline Comment in Condition Statement

This example shows how to use Polyspace Query Language (PQL) to check for violation of this rule: Multiline Comments in condition statements must be aligned.

This topic focuses on application of PQL. For more details about creating syntax defect checkers, see Detect Syntactic Issues Using Polyspace Query Language Syntactic Classes.

Analyze Rule

To implement the rule in PQL, analyze the components of the rule:

  • Comments inside condition statement — This rule applies to multiline comments with in condition statements. There are several way to detect this. In this example, multiline comments with in a condition are detected using these steps:

    • Detect condition statement that spans multiple lines — Find a condition class where the ending line is larger than the start line. See ConditionClause.

    • Find comments that are descendants of the condition clause.

  • Comment alignment — Compare the starting position of two comments that are different descendants of the condition clause

Implement Rule in PQL

The defect can be defined like this:

defect mislignedcomments =
when
  isMultilineCondition(&mlc)
  and mlc.getADescendant(&mlcd1)
  and mlc.getADescendant(&mlcd2)
  and Cpp.Comment.cast(mlcd1, &C1)
  and Cpp.Comment.cast(mlcd2, &C2)
  and C1 != C2
  and C1.startColumn(&pos1)
  and C2.startColumn(&pos2)
  and pos1 < pos2
  raise "Comment misaligned."
on C1
The predicate isMultilineCondition finds condition clauses that span multiple lines:
predicate isMultilineCondition(Cpp.ConditionClause.ConditionClause &mlc){
	return 
	Cpp.ConditionClause.is(&mlc)
	and mlc.startLine(&s)
	and mlc.endLine (&e)
	and s < e
}

Test Defect

To test and verify the defect:

  1. Initialize a test standard in a writable location:

    polyspace-query-language init

  2. In main.pql, insert the defect in a test standard:

    package main

/// Main PQL file defines the catalog of your PQL project.
/// The catalog is a collection of sections.
catalog PQL_AlignCommentAfterIf = {
#[Description("MySection")]
	section mysection = {
#[Description("myRule"), Id(Rule1)]
		rule myRule = {
			defect mislignedcomments =
			when
                isMultilineCondition(&mlc)
				and mlc.getADescendant(&mlcd1)
                and mlc.getADescendant(&mlcd2)
                and Cpp.Comment.cast(mlcd1, &C1)
                and Cpp.Comment.cast(mlcd2, &C2)
                and C1 != C2
                and C1.startColumn(&pos1)
               and C2.startColumn(&pos2)
               and pos1 < pos2
                raise "Comment misaligned."
			on C1
		}
	}
}


predicate isMultilineCondition(Cpp.ConditionClause.ConditionClause &mlc){
	return 
	Cpp.ConditionClause.is(&mlc)
	and mlc.startLine(&s)
	and mlc.endLine (&e)
	and s < e
}

  3. Package the standard in a pschk file:

    polyspace-query-language package

  4. Create example.cpp in the same folder:

    // Copyright 2024 The MathWorks, Inc.
#include <iostream>

int main() {
    int x = 10;

    // Non-compliant code: Comment is not aligned properly after the if statement
    if (x /* AlignCommentsAfterIfStatements: x is an int */
        /*This comment is not aligned properly  //expect-1-Rule1
         */
        > 5) {
      std::cout << "x is greater than 5" << std::endl;
    }

    // Compliant code: Comments are aligned properly after the if statement
    if (x /* x is an int */
          /*This comment is  aligned properly
         */
        > 5) {
      std::cout << "x is greater than 5" << std::endl;
    }

    return 0;
}
    This code explicitly states where a violation of the rule is expected using annotation expect-1-Rule1. Absence of the violation is also annotated using expect-0-Rule1.

  5. Run a test for the defect on the example code:

    polyspace-query-language test example.cpp
    The test verifies the expected violations as well as the expected absence of violations:
    Number of actual defects: 1
Number of expected annotations: 1 (including 0 expected absence of defects).
_______________________________________________
  Checking expected defects with actuals...
  -----------------------------------------
_______________________________________________
  Looking for unexpected defects...
-------------------------------------------
_______________________________________________
Tests passed

See Also

Topics