You might wish to avoid methods with more than 200 lines since they are hard to maintain. After having shrunk all your methods, you certainly want to be notified when during development a method exceeds this threshold. The CQL language addresses this need by allowing the transformation of queries into constraints. For example, here is our previous query rewritten as a constraint:

WARN IF Count > 0 IN SELECT METHODS WHERE NbLinesOfCode > 200 ORDER BY NbLinesOfCode DESC

With almost a hundred keywords, the CQL language allows you to deal with various conditions on your code structure. It allows to write code quality constraints, naming constraints, design constraints, encapsulation constraints, queries on the graph of dependencies, queries on the inheritance tree, queries to get the biggest or smallest code elements according to almost 30 metrics and much more.

CQL and VisualCppDepend

The tool VisualCppDepend allows the editing and execution of CQL queries and constraints. A GUI allows you to have a unique understanding of your application. VisualCppDepend can also be used to generate reports during each build of your application.

VisualNDepend2_Big

Learning the CQL language

Writing CQL queries and constraints is straightforward thanks to the three following features:

The CQL language syntax is close to that of the SQL language syntax. They both share the SELECT TOP xxx FROM xxx WHERE xxx ORDER BY xxx pattern.
The VisualCppDepend CQL editor offers intellisense.
The VisualCppDepend CQL compiler yields verbose errors.

VisualNDependCQLEditor

VisualNDependCQLEditor2

The CQL language and real-world needs

The CQL language has been conceived to understand and control real-world application. In a real-world environment, there are often exceptions (like automatically generated methods which are often very big) and you need to allow a few particular methods to exceed this threshold without being bothered by our previous constraint. The CQL language offers numerous features allowing you to deal with such exceptions. For example, all generated methods might contain the word “Generated” in their names:

WARN IF Count > 0 IN SELECT METHODS WHERE NbLinesOfCode > 200 AND !NameLike "Generated" ORDER BY NbLinesOfCode DESC

Or maybe, all generated methods are in dedicated projects, namespaces or types:

WARN IF Count > 0 IN SELECT METHODS OUT OF NAMESPACES "MyApp.Generated1","MyApp.Generated2" WHERE NbLinesOfCode > 200 ORDER BY NbLinesOfCode DESC

Or maybe, you prefer to mention each one explicitly:

WARN IF Count > 0 IN SELECT METHODS WHERE NbLinesOfCode > 200 AND !(NameIs "Method1(Int32)" OR FullNameIs "MyApp.MyType.Method2(String)" ) ORDER BY NbLinesOfCode DESC

You can also mix all these features in the same constraint:

WARN IF Count > 0 IN SELECT METHODS OUT OF NAMESPACES "MyApp.Generated1","MyApp.Generated2" WHERE NbLinesOfCode > 200 AND !(NameIs "Method1(Int32)" OR FullNameIs "MyApp.MyType.Method2(String)" ) AND !NameLike "Generated" ORDER BY NbLinesOfCode DESC

Storing CQL queries and constraints in your C++ source code

CppDepend stores your CQL queries and constraints in the project file. As the source code is the design you might prefer storing your CQL queries and constraints directly in your source code.

Some examples of queries and constraints written in CQL

Examples of code Quality constraints

WARN IF Count > 0 IN SELECT METHODS WHERE NbLinesOfCode > 200 ORDER BY NbLinesOfCode DESC

// METHODS WHERE NbLinesOfCode > 200 are extremely complex and

// should be split in smaller methods

// (except if they are automatically generated by a tool).

WARN IF Count > 0 IN SELECT METHODS WHERE ILCyclomaticComplexity > 40 ORDER BY ILCyclomaticComplexity DESC

// METHODS WHERE ILCyclomaticComplexity > 20 are hard to understand and maintain.

// METHODS WHERE ILCyclomaticComplexity > 40 are extremely complex and should be split

// in smaller methods (except if they are automatically generated by a tool).

WARN IF Count > 0 IN SELECT METHODS WHERE NbParameters > 5 ORDER BY NbParameters DESC

// METHODS WHERE NbParameters > 5 might be painful to call and might degrade performance.

// You should prefer using additional properties/fields to the declaring type to handle

// numerous states. Another alternative is to provide a class or structure dedicated to

// handle arguments passing (for example see the class System.Diagnostics.ProcessStartInfo

// and the method System.Diagnostics.Process.Start(ProcessStartInfo))

WARN IF Count > 0 IN SELECT METHODS WHERE NbVariables > 15 ORDER BY NbVariables DESC

// METHODS WHERE NbVariables > 8 are hard to understand and maintain.

// METHODS WHERE NbVariables > 15 are extremely complex and should be split in

// smaller methods (except if they are automatically generated by a tool).

WARN IF Count > 0 IN SELECT TYPES WHERE NbMethods > 20 ORDER BY LCOM DESC

// TYPES WHERE NbMethods > 20 might be hard to understand and maintain

// but there might be cases where it is relevant to have a high value for NbMethods.

// For example, the System.Windows.Forms.DataGridView standard class has more than 1000 methods.

WARN IF Count > 0 IN SELECT TYPES WHERE NbFields > 20 AND !IsEnumeration

// TYPES WHERE NbFields > 20 AND !IsEnumeration might be hard to understand and maintain

// but there might be cases where it is relevant to have a high value for NbFields.

// For example, the System.Windows.Forms.Control standard class has more than 200 fields.

// The value of the metric SizeOfInst might be a better indicator of complex type.

WARN IF Count > 0 IN SELECT TYPES WHERE SizeOfInst > 64 ORDER BY SizeOfInst DESC

// TYPES WHERE SizeOfInst > 64 might degrade performance (depending on the number of

// instances created at runtime) and might be hard to maintain.

// However it is not a rule since sometime there is no alternative

// (the size of instances of the System.Net.NetworkInformation.SystemIcmpV6Statistics

// standard class is 2064 bytes).

WARN IF Count > 0 IN SELECT TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10 ORDER BY LCOM DESC

// TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10 might be problematic.

// However, it is very hard to avoid such non-cohesive types. The LCOMHS metric

// is often considered as more efficient to detect non-cohesive types.

WARN IF Count > 0 IN SELECT TYPES WHERE LCOMHS > 1.0 AND NbFields > 10 AND NbMethods >10 ORDER BY LCOMHS DESC

// TYPES WHERE LCOMHS > 1.0 AND NbFields > 10 AND NbMethods >10 should be avoided.

// Note that this constraint is stronger than the constraint

// TYPES WHERE LCOM > 0.8 AND NbFields > 10 AND NbMethods >10.

SELECT TYPES WHERE DepthOfInheritance > 6 ORDER BY DepthOfInheritance DESC

// TYPES WHERE DepthOfInheritance > 6 might be hard to maintain. However it is not

// a rule since sometime your classes might inherit from tier classes which have a

// high value for depth of inheritance. For example, the average depth of inheritance

// for framework classes which derive from System.Windows.Forms.Control is 5.3.

WARN IF Count > 0 IN SELECT TYPES WHERE (SizeOfInst > 200 ) ORDER BY SizeOfInst DESC

// Type with big instances can be problematic

// (Obviously the SizeOfInst metric does not do a deep traverse.

// Any instance reference field will count for 4 bytes.

// It is also unable to cop with generic types properly)

WARN IF Percentage > 15 IN SELECT PROJECTS WHERE NormDistFromMainSeq > 0.7 ORDER BY NormDistFromMainSeq DESC

WARN IF Count > 0 IN SELECT PROJECTS WHERE RelationalCohesion < 1.5 OR RelationalCohesion > 4.0

// As classes inside an project should be strongly related,

// the cohesion should be high. On the other hand, a value which is too high may

// indicate over-coupling. A good range for RelationalCohesion is 1.5 to 4.0.

Examples of naming constraints

WARN IF Count > 0 IN SELECT FIELDS WHERE NameLike "^m_" AND IsStatic

// A static field should not be named 'm_XXX'

WARN IF Count > 0 IN SELECT FIELDS WHERE NameLike "^s_" AND !IsStatic

// A non-static field should not be named 's_XXX'

WARN IF Count > 0 IN SELECT TYPES WHERE IsInterface AND !NameLike "^I"

// The name of an interface should begin with a 'I'

WARN IF Count > 0 IN SELECT TYPES WHERE IsExceptionClass AND !NameLike "Exception$"

// The name of an exception class should end with 'Exception'

WARN IF Count > 0 IN SELECT TYPES WHERE

!NameLike "^[A-Z]" AND // The name of a type should begin with an Upper letter.

!NameLike "__StaticArrayInit" AND // Except __StaticArrayInit generated type

!NameLike "<" // Except C# compiler generated type

WARN IF Count > 0 IN SELECT METHODS WHERE

!NameLike "^[A-Z]"

// The name of a regular method should begin with an Upper letter.

Examples of design constraints

WARN IF Count > 0 IN SELECT TYPES WHERE SizeOfInst ==0 AND !IsStatic AND !IsTemplate

// It indicate stateless types that might eventually be turned into static classes.

Examples of encapsulation constraints

WARN IF Count > 0 IN SELECT FIELDS WHERE IsPublic

// A field should not be public or internal, except for performance reasons.

WARN IF Count > 0 IN SELECT TYPES OUT OF NAMESPACES "System.Xml" WHERE DepthOfIsUsing "System.Xml.XmlChildNodes" == 1

// Restrict the possibility of using the type "System.Xml.XmlChildNodes" only to certain namespace.

WARN IF Count > 0 IN SELECT METHODS OUT OF NAMESPACES "System.Xml" WHERE

DepthOfIsUsing "System.Xml.XmlNamedNodeMap.InsertNodeAt(Int32,XmlNode)"== 1

// Restrict the possibility of calling the method "System.Xml.XmlNamedNodeMap.InsertNodeAt(Int32,XmlNode)"

// only to certain namespace.

WARN IF Count > 0 IN SELECT METHODS OUT OF TYPES

"System.Xml.XmlDocumentFragment",

"System.Xml.XmlEntityReference",

"System.Xml.XmlDocumentType",

"System.Xml.XmlEntity",

"System.Xml.XmlDocument",

"System.Xml.XmlAttribute",

"System.Xml.XmlElement" WHERE DepthOfCreateA "System.Xml.XmlLoader" ==1 ORDER BY DepthOfCreateA

// Restrict the possibility of creating an instance of "System.Xml.XmlLoader" only to certain type.

WARN IF Count > 0 IN SELECT METHODS OUT OF NAMESPACES "System.Xml"

WHERE DepthOfCreateA "System.Xml.XmlLoader" == 1 ORDER BY DepthOfCreateA

// Restrict the possibility of creating an instance of "System.Xml.XmlLoader" only to certain namespaces.

WARN IF Count > 1 IN SELECT NAMESPACES OUT OF PROJECTS "System.Windows.Forms"

WHERE DepthOfIsUsing "System.Windows.Forms.Internal" == 1

// Restrict the possibility of using a namespace only to one project.

WARN IF Count > 0 IN SELECT METHODS OUT OF NAMESPACES "System.Windows.Forms" WHERE

DepthOfIsUsing "System.Windows.Forms.DataGridView+HitTestInfo.typeInternal" == 1

// Restrict the possibility of using the field

// "System.Windows.Forms.DataGridView+HitTestInfo.typeInternal"

// only to certain namespace.

Examples of queries on the graph of dependencies

SELECT METHODS WHERE IsUsing "System.Xml.XmlWriter..ctor()" ORDER BY DepthOfIsUsing

// 'IsUsing/IsUsedBy/DepthOfIsUsing/DepthOfIsUsedBy' conditions are useful

// to understand who calls statically who for example to anticipate future impacts

// of some refactoring or to provide some customized encapsulation constraints.

SELECT METHODS WHERE DepthOfIsUsing "System.Xml.XmlWriter..ctor()" <=3

// 'IsUsing/IsUsedBy/DepthOfIsUsing/DepthOfIsUsedBy' conditions are useful

// to understand who calls statically who for example to anticipate future impacts

// of some refactoring or to provide some customized encapsulation constraints.