In an effort to make communication between teams easier we used a CQL query like this to report changes to these methods as part of our automated builds:

This was nice, but it only got us part of the way there. This would alert us to signature changes or changes to the content of the method, but not necessarily changes to the message contracts passed in to the method. In Pseudo-CQL the query I had in mind looks something like this:

This didn't work however (CQL doesn't really have support for subqueries), and I couldn't really find anything in the language that would allow us to achieve what we wanted. NDepend 4 introduces a new linq-based replacement called CQLinq that offers a lot more flexibility, so I figured I would see if I could write the query that we needed using it. It ended up being much easier than I thought - CQLinq gives us access to most (if not all) of the standard LINQ operators, and the same functions for querying code using attributes and history that we had with CQL. This is the query I came up with:

Once we have the query we can mark it as critical, so we will have a failing build after the changes are made. Only the first build after making the changes should fail, but that would be enough to trigger an investigation that would result in communicating the changes to the other team.

CQL has always been my favorite feature of NDepend, so its no surprise that CQLinq is my favorite feature in this new release. The LINQ based syntax feels much more natural to me when writing queries against a codebase than the SQL-like syntax of CQL, and still gives us all the same visualization goodies to foster quick understanding of the query results. I'm really excited to dig in a little more and see what else I can do with it.

My favorite feature of NDepend has always been CQL, the SQL-like query language that allows you to query your codebase using a variety of common metrics. This is the same as it ever was (the integration with VS is even quite similar) but with the more thorough integration it seems much more useful. I like how easy it is now to keep an eye on my CQL constraints when I rebuild.

My favorite CQL feature is the ability to set up CQL constraints from now. This is really cool for older projects, where it's unrealistic to think that your team will be able to fix everything right away. But what you can do with this feature is ensure that all new or modified code does measure up to your team's standards. You may not be able to clean up all those 1,000 line methods right away, but you can ensure that newer methods fit in a more reasonable size limit (like 975 ). This is one of the most useful features of the application, IMO. The way it works is by allowing you to establish a baseline. By comparing the code's current state to this baseline, future analyses are able to determine which methods/types/etc are new or changed, and apply the constraint to only these methods/types/etc. Sometimes I feel like this would be useful just to be able to concisely see which methods have been changed as well (version control logs aren't the most friendly things to read, especially spread throughout a large codebase). Below is a screenshot of this feature in action.

The first three queries listed are built in to NDepend. I added the fourth, just to have a listing of new/changed methods ready. The CQL for this query is simply

Not a bad way to keep an eye on what is getting changed in the codebase. To get in this state I added three new methods to the codebase I was looking at (in a place that I could remove them easily since they are not only low quality but useless as well). Two had 7 parameters, putting them in violation of the constraint for basic quality principles. I didn't add any tests, so all three were in violation of the test coverage constraint. And finally they all showed up in the list of new methods. It's worth noting the yellow circle at the bottom right as well - the yellow means that warnings were encountered when running the CQL portion of the analysis. Green would be good, and red would mean I have some bad queries that can't be run.

Double clicking a row in the CQL Explorer will take you to the CQL Editor - from here you can view the results of the query, and the CQL it contains. From there you can easily navigate to the method definition in your source code by double-clicking.

One of the things I really like here is the comments in the built-in queries. They contain numerous links to metric definitions on the NDepend website, and sometimes even links to blog entries where the lead developer, Patrick Smacchia has explained features in greater detail. I really like this form of documentation, it makes it easier to keep up to date and also minimizes what needs to be stored on the user's computer.

What I was happiest to find in the VS integration is the ability to superimpose CQL results onto the metrics view. The metrics view consists of a grid where each block represents a unit of code (type, method, etc...) and they are sized according to their value for the metric in question. When running CQL queries, the units of code matching your criteria are highlighted, giving a great visualization of how much code exhibits the properties you are looking for.

The selected query (about types having too many efferent couplings) is the currently selected query, and I had moused over the QueryParser class to highlight it in pink and show the metrics summary on the right. I find that having this built right into visual studio really helps me figure out where to focus my refactoring energy.

It looks as if a lot of effort went into making the CQL validation phase fast:

CQL rules validation phase is fast. The performance challenge was to make this happens almost instantly to avoid slowing the developer machine. Hopefully for a large 100K Lines of Code application, code gets re-analyzed and 200 CQL rules can get checked, all within 3 seconds after the (re)compilation of one or several .NET assemblies. These fast performances were made possible thanks to the development of a new technology of incremental code analysis. With incremental code analysis, only modified code gets re-analyzed. I can attest that this was extremely challenging and complex development!

From what I've seen, the effort's been a success. I've mostly been using it to look at different versions of Lucene.net, as I've got some work to do to get some of my code to build in VS2010. For this size codebase (~23k lines) the analysis is completed very quickly, even if I disable the incremental analysis. The CQL validation portion completes almost instantly, and memory usage doesn't seem to get out of hand even when keeping VS open for days. I'd imagine if your computer can handle running Visual Studio to begin with, it won't have too much trouble with the NDepend integration. I could see some of the VS add-ins that don't play well with others causing issues, especially with a very large codebase, so I hope to go back and test with a larger codebase and some other add-ins installed eventually.

Most of the other NDepend goodies are available in VS now as well (Dependency Graphs, Test Coverage Analysis, Class Browser, etc...) but I won't get into all that here. I really see CQL as the app's killer feature, and that is what I spend the most time thinking about. There is a good overview of the app's capabilities here if you'd like to read more.

For this example, I'll use a Layer Diagram for an imaginary application with Web, Business and Data tiers, and some shared model objects. This is an intentionally oversimplified example.

Anyway here's what the diagram looks like:

Nothing really special here - the words are the name of the tier, and the numbers are the number of units of code (in this case projects, but you can add individual namespaces or classes as well). To create the diagram, we need to first create a new Visual Studio Modeling Project. A new layer diagram can then be added to this project. I used the designer to add the shapes and dependency lines, and all looks good. But we want to do more than look at it!

This is where things get interesting. To place modules into one of the tiers, you can drag and drop either from the Solution Explorer or from the new Architecture Explorer. Both have different ways of finding the objects you are looking for, but the result is the same. Once all modules are allocated to the right layer, you can right click the diagram and choose "Validate Architecture".

Visual Studio will then build your solution and validate its architecture. If all goes well, you'll see something like this in the output window:

1/28/2010 4:04:17 PM: Architecture validation is starting.
1/28/2010 4:04:23 PM: Architecture validation succeeded (0 suppressed).

Now, let's try adding an illegal call, in this case from the data tier to a caching provider found in the web tier (I first tried adding a reference to the "Biz" project, but was not allowed because it would introduce a cyclic dependency - I guess this was in previous versions but I never ran into it before - pretty cool).

After this call is added, try validating the architecture again. The solution will be rebuilt, and you'll see something like this:

1/28/2010 4:19:46 PM: Architecture validation is starting.
1/28/2010 4:19:55 PM: Architecture validation failed with 3 violation(s) (0 suppressed).

Ok, so we have violations, just as expected. Clicking over to the error list you can find what exactly the errors are.

So, not only do the undesirable calls added to the Data Layer's code trigger violations, but the reference itself does as well. There are a few things of interest that we can do with the errors from here.

When right clicking the error, you can choose "Manage Validation Errors" from the context menu, and then "Suppress Errors". Well, as long as you're willing to do it at your own risk . Then you'd end up with a build output like this:

1/28/2010 4:25:03 PM: Architecture validation is starting.
1/28/2010 4:25:09 PM: Architecture validation succeeded (3 suppressed).

Knowing our readership, I doubt this will be an option though. So what can be done about this? If you want to fix the error immediately, you can double click the error message and be taken to the offending code, just as you would for a syntax error if a normal build failed. If you use Team Foundation Server, you can also select "Create Work Item" to create a new TFS work item based on the error.

This can also be included as part of your local build process by setting the "Validate Architecture" property of the Modeling Project. TFS users can also add this step to their team build by opening the Compilation tab and adding the following to the MSBuild arguments section:

/p:ValidateArchitecture=true

Adding this to the team build is especially cool, because you can actually block check-ins that introduce these kinds of architectural problems.

I am really excited to see this kind of stuff getting more attention in Visual Studio. I'm not sure if these new components will be able to do everything I've come to expect (and love) from NDepend, but their presence is a huge step forward for Visual Studio, and I think for the .net community in general. I'm a big believer in the use of static code analysis as a tool for better understanding the code we work with, and I think that making these tools available to more developers (especially those in shops that are reluctant to use non-Microsoft components or tooling) will really help us continue to improve as a group.

I noticed while writing this post that the latest beta of NDepend 3 is now fully integrated with Visual Studio. I'd meant to do a future post comparing the DGQL queries available in Visual Studio 2010 with NDepend's CQL, but perhaps a more thorough comparison will be in order.