Why is ReaderWriterLockSlim missing from Enterprise Library 4?

With the release of Enterprise Library 4 I thought for sure the Caching Application Block's use of the simple System.Threading.Monitor would be replaced with the new ReaderWriterLockSlim that is part of .Net 3.5. After all, Jeffrey Richter was right about the slow performing ReaderWriterLock, and now there is a better solution than what was in Enterprise Library 3.1, right? Yet in the source of EL 4 you can still find the calls to Monitor and some simple lock(object) statements. It seems like an easy performance win to me, but hopefully there is a good reason it's not included that I just don't know about.

Documentation is Modeling

I've had the opportunity to discuss the value of documentation as a part of the software creation process lately. I hadn't noticed until then how much my views were influenced by a couple of pages in Agile Principles, Patterns, and Practices in C# by Robert and Micah Martin. The book is absolutely phenomenal and has had a strong influence on my development in the last few years. There's a small transition between two sections of the book as it leads out of principles and into modeling practices. That transition struck a cord with me in regards to documentation and that cord is resonating loudly as of late.



Modeling
A bridge builder creates a model to test the strength to weight ratio of the bridge. An airplane designer creates a model to put it in the wind tunnel to test the aerodynamics of the design. The bridge and airplane models were smaller versions of the real thing built to learn something about how to better build the real thing. Why smaller? Smaller is cheaper in these cases. An important aspect of modeling is that the model is cheaper to build than the real thing. If the model is more expensive to build than the real thing it wouldn't be providing any strategic value, you could just skip building the model and go straight to building the real thing. The second value in the bridge and airplane models is that they were built to be tested. One was tested by how much weight it could hold, one was tested to see how efficiently it could move through the air. Without being tested the models provide no value, they're just like the model car kits I put together as a kid, they're fun to look at but not good for anything else. Without testing the model you don't learn anything about building the real thing.



Value from Modeling
Modeling provides value only when both of the following are true. Without both being true modeling is just wasted work to create something pretty to put on a shelve and admire.

1. The model is cheaper to build than the real thing.


2. The model is built to be tested to figure out how to build a better real thing.

Modeling Software
Software is no different from the bridge or aerospace industries in regards to modeling. We model software by writing something down on a piece of paper, whiteboard, or napkin to express the characteristics and designs of the real thing. We then test that model by asking our peers, customers and other knowledgeable people if their assumptions, scenarios, goals, etc are all fulfilled by the model. Their answers determine how much the real thing will reflect the model, or if remodeling needs to be done. Modeling in software takes many forms, UML, requirements documents, technical specifications, test cases, use cases, etc. They are however all textual models that can be tested to prove some virtual characteristic of the software.



Value From Documentation
Thus, applying the two points above that determine when modeling is valuable we can determine when to document and how to get the most value out of documentation.

1. Documentation should be relatively cheap.


2. Documentation should be created when we want to test the software before building it.

To get the most from documentation we should only create it when we need to test and when we can create the documentation and test it cheaper than creating and testing the software. I think the key point that is often missed is that the documentation needs to be easily testable. Documentation in thesis form might be a well written masterpiece but it's not easily testable. To figure out if a particular scenario will be fulfilled I would have to read the whole document to find all the references for impacts to that scenario and then compose them into one and apply my scenario test. That is not cheap, nor easy. Modeling software with User Stories however is much easier to test because the model is organized into identifiable pieces of work in the way that the development team builds and tests the software. This results in a shared thought pattern (ahem, mental model) by the entire team - the modelers and the builders. User Stories convey the virtual characteristics in ways that allow for cheaper and easier testing of the documentation in order to build better software.

So, as we create documentation to help us build software we should ask ourselves:

1. Is this documentation testable? (If no - then don't create it.)
2. Can something be learned about the software by testing this documentation? (If no - then don't create it)
3. How can I make this documentation cheaper to build and maintain?
4. How can I make this documentation easier to Test?

Changing FxCop Maintainability and Cyclomatic Complexity rules

I'm finally moving to VSTS 2008, and yesterday I spent some time playing with the new Maintainability index. I am a big fan of NDepend and have used it for a year or so now in an effort to create more sustainable code, thus the new Maintainability index was promising to me. However, after finding out the range for the index is 0 - 100 and the thresholds are 10 for an error and 20 for a warning I was again disappointed with the extremely conservative implementation, just like I was with the high Cyclomatic Complexity thresholds.

How to change the thresholds
I started out trying to use the same approach that worked with 2005 in order to change the FxCop thresholds for these two rules. However editing the IL and reconstituting the Maintainability.dll without the strong name doesn't work anymore with 2008 because it references two other strong named assemblies. Also, I was never really ethically satisfied with the old approach any way.

After looking at the assembly with Reflector and reading a great tutorial on creating FxCop rules I started approaching the problem with the Decorator pattern to wrap the existing rules with my own. I assumed then that I could deactivate the Microsoft shipped version of the rules and activate my own in each Vs.Net project's Static Analysis settings. Implementing the Decorator pattern was a bit tricky though because the existing rules have both the Internal and Sealed modifier so I couldn't simply "new up" an instance nor could I inherit from the shipped types and override the pieces I wanted to augment. Luckily reflection provides a way to do everything that I needed even though the type signatures don't.

What I ended up with was a new JBBrown.FxCop.Rules.dll containing 3 class definitions - 1 abstract class and 2 new FxCop rules that implement the abstraction. The abstract class does the work of instantiating the Microsoft shipped rule, setting the thresholds and delegating FxCop API calls off to the decorated instance. The two new rules specify the new threshold values by providing the names of private variables within the Microsoft shipped rules to be reset to new custom chosen values. This is what the resulting VS.Net project's Static Analysis settings looks like when using the Decorated rules.





The Code
The entire source can be found here to allow you to set your own preferred thresholds for the Maintainability and Cyclomatic Complexity FxCop rules. After you compile the project then just drop the dll in your Rules directory and restart your Vs.Net. The FxCop rule directory path should be similar to "C:\Program Files\Microsoft Visual Studio 9.0\Team Tools\Static Analysis Tools\FxCop\Rules"

TeamReview 1.0.2: Code Review - just a lot less painful

A few days ago I released TeamReview version 1.0.2, which introduced integrated IDE support for Code Review Item closing/editing during the Code Review Replay process. Also, thanks to Maarten Balliauw a bug was fixed for VSTS 2008.

If you could benefit from cheaper, easier and more valuable code review TeamReview might be your answer; check out this TeamReview Example