Advanced PRQL Features

This section details advanced capabilities of PRQL (Code Query LINQ), CppDepend's query language for analyzing C/C++ code. From querying debt and quality gates to exploring code dependencies and naming conventions, PRQL provides powerful facilities for deep code analysis.

Introduction

From the introduction of CppDepend v2017.1 PRQL is not just about code querying but also about querying Debt, Issues, Rules and Quality Gates.

This feature is useful for in-depth exploration of the technical-debt. In the technical debt documentation we demonstrate how a few clicks from the Dashboard can generate queries to explore the debt and the issues.

This feature is also useful to define custom Trend Metrics, Quality Gates and Rules.

For example a Quality Gate that would define thresholds concerning the percentage of technical-debt could look like:

1// <QualityGate Name="Percentage Debt" Unit="%" />
2
3failif value > 30%
4
5warnif value > 20%
6
7let timeToDev = codeBase.EffortToDevelop()
8
9let debt = Issues.Sum(i => i.Debt)
10
11select 100d * debt.ToManDay() / timeToDev.ToManDay()

A Trend Metric that would count the number of critical rules violated could look like:

1// <TrendMetric Name="# Critical Rules Violated" Unit="rules"/>
2
3from rule in Rules
4
5where rule.IsViolated() && rule.IsCritical
6
7select new {
8
9   rule,
10
11   issues = rule.Issues(),
12
13   debt = rule.Debt(),
14
15   annualInterest = rule.AnnualInterest(),
16
17   maxSeverity = rule.Issues().Max(i => i.Severity)
18
19}

Not only this Trend Metric is useful to follow the trend, but its result is also browsable for in-depth exploration:

Querying diff since the Baseline

When a baseline is available, rules are passed against the baseline in addition to being passed against the actual code base snapshot. As a result CppDepend can compare both issues sets: the issues set obtained by passing rules on the baseline and the issues set obtained by passing rules on the actual code base snapshot.

PRQL can then be used to query the Debt, Issues, Rules and Quality Gates diff. For example a Trend Metric that counts the new issues since baseline could look like:

1// <TrendMetric Name="# New Issues since Baseline" Unit="issues"/>
2
3from issue in Issues
4
5where issue.WasAdded()
6
7select new { issue, issue.Debt, issue.AnnualInterest, issue.Severity }

A Quality Gate that would forbid more than 2 man-days of technical debt since the baseline could look like:

1// <QualityGate Name="New Debt since Baseline" Unit="man-days" />
2
3failif value > 2 man-days
4
5warnif value > 0 man-days
6
7let debt = Issues.Sum(i => i.Debt)
8
9let debtInBaseline = IssuesInBaseline.Sum(i => i.Debt)
10
11select (debt - debtInBaseline).ToManDay()

A dozen of Quality Gates are defined by default, and it is easy to customize them and to create new ones. In the screenshot below, this query (generated by a single click on the Dashboard) shows not only the Quality Gates actual status, but also the Quality Gates status on baseline. Quality Gates that rely on diff cannot be passed against the baseline and this is why they have a Not Available N/A value.

In the same way, many Trend Metrics related to Debt, Issues, Rules and Quality Gates are defined by default and it is easy to customize them and create new ones.

The dashboard proposes several menus to generate queries to explore the Debt, Issues, Rules and Quality Gates status Any number is clickable too to generate a query that lists the counted items.

How it works

Specialized types are defined by the CppDepend.API to specify the debt model, including Debt ; IIssue ; IRule ; IQualityGate ; QualityGateStatus.

However the two key types are: IIssuesSet ; IIssuesSetDiff.

• First CppDepend runs the activated rules both on the actual snapshot and on the baseline.
• It computes issues, debt numbers and diff.
• Then it populates these issues-set and issues-set-diff objects.
• Queries that rely on issues-set and issues-set-diff are executed only once these sets are filled. As a consequence a Rule cannot rely on these sets, but a Quality Gate can.

Instead of writing a query like...

1from i in context.IssuesSet.AllIssues select i

...or like...

1from i in context.IssuesSetDiff.OlderIssuesSet.AllIssues select i

...4 domains are proposed by PRQL: Issues, IssuesOnBaseline, Rules and QualityGates.

These domains are shortcuts for context.IssuesSet.AllIssues, context.IssuesSetDiff.OlderIssuesSet.AllIssues, context.IssuesSet.AllRules and context.IssuesSet.AllQualityGates.

These domains can be seen as range variables of type: IEnumerable ; IEnumerable ; IEnumerable.

With these domains, simple queries can then be written like...

1from i in Issues select i

...or even just:

Issues

The same way instead of constantly referring to issues-set and issues-set-diff to obtain data like for example...

1from codeElement in CodeElements
2
3where context.IssuesSet.HasIssue(codeElement)
4
5select new {
6
7   codeElement,
8
9   issues = context.IssuesSet.Issues(codeElement),
10
11   newIssues = context.IssuesSet.Issues(codeElement)
12
13               .Where(i => context.IssuesSetDiff.WasAdded(i))
14
15}

...the types IssuesSet and IssuesSetDiff propose convenient extension methods which are automatically translated by the PRQL compiler to calls on context.IssuesSet and context.IssuesSetDiff.

For example the query above can be rewritten:

1from codeElement in CodeElements
2
3where codeElement.HasIssue()
4
5select new {
6
7   codeElement,
8
9   issues = codeElement.Issues(),
10
11   newIssues = codeElement.NewerIssues()
12
13}

The full list of extension methods proposed is:

• HasIssue() / HasNewIssue() / HasIssueOnBaseline()
• Debt() / NewDebt() / DebtOnBaseline()
• AnnualInterest() / NewAnnualInterest() / AnnualInterestOnBaseline()
• Issues() / NewerIssues() / IssuesOnBaseline()
• RulesViolated() / RulesViolatedOnBaseline()
• QualityGatesStatus() / QualityGatesStatusOnBaseline()

Note that when working with a property like AnnualInterest, the type Debt returned defines an implicit conversion to TimeSpan (because a debt is a certain number of man-time to fix). Hence the sub-query can be written:

1let annualInterest = Issues.Sum(i => i.AnnualInterest)

Here annualInterest can be of type Debt or TimeSpan. This is also the case for a sub-expression like:

1let debt = codeBase.TechnicalDebt
2
3let annualInterest = debt.AnnualInterest

...which can be rewritten:

1let annualInterest = codeBase.TechnicalDebt.AnnualInterest

Each time you write a code query, you are writing a query against the set of types, methods and fields of your code base model. Hence the code elements are central objects.

Here is a simple query that shows how to enumerate the base classes of a class:

1from t in Application.Types where t.NameLike ("MyClass")
2
3select new {
4
5  t,
6
7  baseClasses = t.BaseClasses }

And here is a query that shows how to enumerate methods overridden by a method, and methods that override a method:

1from m in Application.Methods where m.NameLike ("MyMethod")
2
3select new {
4
5  m,
6
7  // Enumerates methods overridden by m
8
9  m.OverriddensBase,
10
11  // Enumerates methods that overrides m directly
12
13  m.OverridesDirectDerived,
14
15  // Enumerates methods that overrides m directly or indirectly
16
17  m.OverridesDerived }

Go to top

The dependency model is general in the sense that it doesn't rely on the kind of usage (field assignment, method call...). A and B being two code elements, we say that A depends on B if, when B is not available, A cannot be compiled.

Here's a sample of dependency query:

1from m in Methods where
2
3	m.IsUsing("MyType") &&
4
5	m.IsUsedBy("MyProjectName".AllowNoMatch())
6
7select m

Notice how such extension methods are used by rules generated from dependency graph or dependency matrix, to forbid some particular dependency:

The rule generated is shown below. It could be easily adapted to forbid or enforce any dependency in a code base.

CppDepend provides also a convenient way to query dependencies of a code base (and often a faster way as well):

1from t in Types.UsedByAny(Types.Where(t => t.IsStatic)) select t

Indirect Usage

CppDepend provides some methods containing the word Indirect in their names,to deal with indirect dependencies like for example, the method IsIndirectlyUsing().

For example if A is using B that is using C, A is not directly using C but A is indirectly using C (with a depth of 2).

Here is a query that enumerates methods that are directly or indirectly calling the Print method MyClass.Print().

1from m in Methods
2
3	let depth0 = m.IsIndirectlyUsing("MyClass.Print()")
4
5select m

The method DepthOfIsUsing goes further since it returns the depth of usage.

1from m in Methods
2
3	let depth0 = m.DepthOfIsUsing("MyClass.Print()")
4
5	where depth0  >= 0 orderby depth0 ascending
6
7select new { m, depth0 }

The depth returned is a Nullable value.

• It is null if m doesn't call indirectly the target method.
• It is 1 if m calls directly the target method.
• It is greater than 1 if m calls indirectly the target method.

This indirect usage possibility is especially useful to generate Call Graphs or Class Inheritance Graphs.

Some of the methods also contain the word Indirect or the word Depth to work with indirect usage from a sequence to a code element or even any code elements of a target sequence (suffix Any).

For example, the following query matches all methods that are calling, directly or indirectly the static methods, with the depth of call:

1let statics = Methods.Where(m => m.IsStatic).ToHashSet()
2
3	let depthMetric = Application.Methods.DepthOfIsUsingAny(statics)
4
5	from m in depthMetric.DefinitionDomain
6
7	let depthValue = depthMetric[m]
8
9	orderby depthValue ascending
10
11select new { m, depthValue }

Go to top

CppDepend computes more than 80 code metrics.

1// <Name>Quick summary of methods to refactor</Name>
2
3warnif count > 0 from m in JustMyCode.Methods where
4
5  // Code Metrics' definitions
6
7  m.NbLinesOfCode > 30 ||  // http://www.cppdepend.com/documentation/code-metrics#NbLinesOfCode
8
9  m.CyclomaticComplexity > 20 ||  // https://www.cppdepend.com/documentation/code-metrics#CC
10
11  m.NestingDepth > 5 ||  // http://www.cppdepend.com/documentation/code-metrics#ILNestingDepth
12
13  m.NbParameters > 5 ||  // http://www.cppdepend.com/documentation/code-metrics#NbParameters
14
15  m.NbVariables > 8 ||  // http://www.cppdepend.com/documentation/code-metrics#NbVariables
16
17  m.NbOverloads > 6  // http://www.cppdepend.com/documentation/code-metrics#NbOverloads
18
19select new { m, m.NbLinesOfCode, m.CyclomaticComplexity,
20
21             m.NbParameters, m.NbVariables, m.NbOverloads }

Notes that many of these code metrics returns a nullable numeric value because they are not necessarily defined for all code elements. For example the #Lines of Code is not computed for third-party code elements.

Custom Metrics

Thanks to the LINQ flexibility it is easy to compose the default code metrics to create more elaborated code metrics, like for example:

1// <Name>Custom metric</Name>
2
3warnif count > 0
4
5from m in JustMyCode.Methods
6
7// Don't match too short methods
8
9where m.NbLinesOfCode > 10
10
11let CC = m.CyclomaticComplexity
12
13let CustomMetric = (CC * CC )/100
14
15where Custom != null && Custom > 30
16
17orderby Custom descending, m.NbLinesOfCode descending
18
19select new { m, Custom, CC, m.NbLinesOfCode }

A custom code metric object can also be obtained from the method FillIterative(). For example, this possibility is used in the rule to obtain dead types, but also to obtained types only used by dead type (and the depth of usage):

1// <Name>Potentially dead Types</Name>
2
3warnif count > 0
4
5// Filter procedure for types that should'nt be considered as dead
6
7let canTypeBeConsideredAsDeadProc = new Func<IType, bool>(
8
9	t => !t.IsPublic && //   Public types might be used by client applications of your projects.
10
11	     !t.IsGeneratedByCompiler)
12
13// Select types unused
14
15let typesUnused =
16
17   from t in JustMyCode.Types where
18
19   t.NbTypesUsingMe == 0 && canTypeBeConsideredAsDeadProc(t)
20
21   select t
22
23// Dead types = types used only by unused types (recursive)
24
25let deadTypesMetric = typesUnused.FillIterative(
26
27         types => from t in codeBase.Application.Types.UsedByAny(types).Except(types)
28
29               where canTypeBeConsideredAsDeadProc(t) &&
30
31               t.TypesUsingMe.Intersect(types).Count() == t.NbTypesUsingMe
32
33         select t)
34
35from t in deadTypesMetric.DefinitionDomain
36
37select new { t, t.TypesUsingMe, depth = deadTypesMetric[t] }

Go to top

CppDepend comes with the unique feature to compare two different snapshots of a code base to see what was changed/added/removed.

For example, the following query enumerates methods where code has been changed:

1from m in Application.Methods
2
3where context.CompareContext.CodeWasChanged(m)
4
5select m

Actually you can just write the shortest query below, and the PRQL compiler will take care to transform it into the query above:

1from m in Application.Methods
2
3where m.CodeWasChanged()
4
5select m

Once such query is written, the CppDepend UI offers the capability to compare the two source files versions of the method changed.

Notice the two methods OlderVersion() and NewerVersion() . As their names suggest, these methods returns the older or newer version of a code element, or null if the code element has been added (hence no older version) or removed (hence no newer version). These methods can be useful for example to write the query below that tracks the evolution in terms of method complexity:

1// <Name>Methods that became more complex</Name>
2
3from m in codeBase.OlderVersion().Methods
4
5where m.IsPresentInBothBuilds()
6
7let oldCC = m.CyclomaticComplexity
8
9let newCC = m.NewerVersion().CyclomaticComplexity
10
11where oldCC != null && newCC > oldCC
12
13select new { m, oldCC, newCC }

Notice the call to IsPresentInBothBuilds to ensure that we only deal with methods that are both in the older and newer code base snapshot, to prevent any NullReferenceException while running the query!

As this last query shows, mixing the diff feature with others PRQL features like code quality metrics or dependencies, can lead to powerful code queries and rules to track the evolution of a code base.

Go to top

PRQL proposes several facilities to query the name of the code elements. This is especially useful to write simple code naming conventions (based on regular expressions)...

1// <Name>Abstract base class should be suffixed with 'Base'</Name>
2
3warnif count > 0 from t in Application.Types where
4
5  t.IsAbstract &&
6
7  t.IsClass &&
8
9  t.DepthOfInheritance == 1 &&
10
11  ((!t.IsGeneric && !t.NameLike (@&quot;Base$&quot;)) ||
12
13  ( t.IsGeneric && !t.NameLike (@&quot;Base&lt;&quot;)))
14
15select new { t, t.DepthOfInheritance }

...or smart code naming conventions:

1// <Name>Avoid naming types and namespaces with the same identifier</Name>
2
3// Not only this can provoke compiler resolution collision,
4
5// but also, this makes code less maintainable because
6
7// concepts are not concisely identified.
8
9warnif count > 0
10
11let hashsetShortNames = Namespaces.Where(n => n.Name.Length > 0).Select(n => n.SimpleName).ToHashSet()
12
13from t in JustMyCode.Types
14
15where hashsetShortNames.Contains(t.Name)
16
17select new { t, namespaces = Namespaces.Where(n => n.SimpleName == t.Name) }

The code elements naming feature is summarized in the PRQL syntax document, in the section Matching code elements by name string.

Go to top

The concept of immutability is becoming more and more popular. Immutability is especially useful when dealing with concurrent accesses into multi-threaded environment.

A type is considered as immutable if its instance fields cannot be modified once an instance has been built by a constructor. A static field is considered as immutable if it is private and if it is only assigned by the static constructor. An instance field is considered as immutable if it is private and if it is only assigned by its type's constructor(s) or its type's static constructor. Notes that a field declared as readonly is necessarily immutable, but a field can be immutable without being declared as readonly. In this last case, the keyword readonly can be added to the field declaration, without provoking any compilation error.

At analysis time, CppDepend computes the mutability of types and fields. The result is available through the properties Type.IsImmutable and Field.IsImmutable.

It is then easy to write such rule for example:

1// <Name>Structures should be immutable</Name>
2
3warnif count > 0 from t in Application.Types where
4
5   t.IsStructure &&
6
7   !t.IsImmutable
8
9let mutableFields = t.Fields.Where(f => !f.IsImmutable)
10
11select new { t, t.NbLinesOfCode, mutableFields }

The two properties ChangesObjectState and ChangesTypeState can be use to enforce or check that a method is pure. A pure method is a method that doesn't assign any instance or static fields.

Also, to control the write access to a particular field, you can use the extension method AssignField():

1from m in Methods where m.AssignField("MyClass.myfield")
2
3select new { m, m.NbLinesOfCode }

In addition, CppDepend provides for fields the 3 properties MethodsAssigningMe , MethodsReadingMeButNotAssigningMe and MethodsUsingMe and for methods it provides the AssignField() method.

Go to top

For each code element you can access to their SourceDecls. Having access to source file declarations opens a range of interesting applications. For example the default query matching methods to discard from the JustMyCode code base view, relies on some patterns on source file name, and can be easily adapted to any situation:

1// <Name>Discard generated and designer Methods from JustMyCode</Name>
2
3// --- Make sure to make this query richer to discard generated methods from CppDepend rules results ---
4
5notmycode
6
7//
8
9// First define source files paths to discard
10
11//
12
13from a in Application.Projects
14
15
16let projectSourceFilesPaths = a.SourceDecls.Select(s => s.SourceFile.FilePath)
17
18let sourceFilesPathsToDiscard = (
19
20    from filePath in projectSourceFilesPaths
21
22    let filePathLower= filePath.ToString().ToLower()
23
24    where
25
26    filePathLower.Contains(&quot;generated&quot;)
27
28    select filePath
29
30).ToHashSet()
31
32//
33
34// Second: discard methods in sourceFilesPathsToDiscard
35
36//
37
38from m in a.ChildMethods
39
40where (sourceFilesPathsToDiscard.Contains(m.SourceDecls.First().SourceFile.FilePath))
41
42select new { m, m.NbLinesOfCode }

Several default rules concerning source files organization are proposed when you create a new CppDepend project.