Rory Primrose

I was reminded this morning of an email that I sent to the junior developers on my team when they joined us. It is an overview of some of the development practices, patterns and products that they would get exposed to on our project. I have included it here as a reference collection for others.

Principles and Patterns

These are things that I often use and are still learning to use.

• SOLID – Originally put together by Bob Martin (http://butunclebob.com/ArticleS.UncleBob.PrinciplesOfOod). A good overview to read is at http://www.davesquared.net/2009/01/introduction-to-solid-principles-of-oo.html.
• LoD - Law of Demeter (or Principle of Least Knowledge) (http://en.wikipedia.org/wiki/Law_of_Demeter). Often referred to as loose coupling.
• DRY – Do not Repeat Yourself (http://en.wikipedia.org/wiki/Don't_repeat_yourself). Many say that this principle should not apply to unit testing.
• DIP – Dependency Injection Pattern which is the D in SOLID. Jeremy Miller has a good overview at http://codebetter.com/blogs/jeremy.miller/archive/2005/10/06/132825.aspx. Dependency Injection frameworks (Unity, Castle Windsor, Spring.Net etc) often use a Service Locator pattern for their implementation. Like Jeremy, my preference is constructor injection because it defines a contract of how to use a class whereas setter (or property) injection doesn’t. Setter injection should only be used for optional dependencies and usually requires additional defensive coding.
• TDD – Test Driven Development (http://en.wikipedia.org/wiki/Test-driven_development)
• DDD – Domain Driven Design is gaining popularity but still seems to be not well understood or widely used (including by me). See http://en.wikipedia.org/wiki/Domain-driven_design and MSDN Mag introduction article at http://msdn.microsoft.com/en-us/magazine/dd419654.aspx.
• AOP – Aspect Orientated Programming (http://en.wikipedia.org/wiki/Aspect-oriented_programming)
• Service Locator – See http://en.wikipedia.org/wiki/Service_locator_pattern and http://msdn.microsoft.com/en-us/library/cc707905.aspx. Keep in mind that this is starting to be considered as an anti-pattern and should probably be avoided in favour of Dependency Injection.
• GOF - Gang of Four patterns (http://www.dofactory.com/Patterns/Patterns.aspx). I tend to use the following in GoF:
  • Factory Method- See http://www.dofactory.com/Patterns/PatternFactory.aspx
  • Facade - See http://www.dofactory.com/Patterns/PatternFacade.aspx
  • Proxy – See http://www.dofactory.com/Patterns/PatternProxy.aspx
  • Chain of Responsibility – See http://www.dofactory.com/Patterns/PatternChain.aspx. While I haven’t used this one, it would be very helpful for processing items in a queue.
• Testing - http://en.wikipedia.org/wiki/Software_testing. Lots of areas to cover such as white box, black box, grey box, regression, non-functional (performance, load, globalisation), unit vs. integration testing, code coverage etc.
  • Mocking – Used to provide mock dependencies for unit testing. See http://en.wikipedia.org/wiki/Mock_object, http://martinfowler.com/articles/mocksArentStubs.html and http://msdn.microsoft.com/en-us/magazine/cc163904.aspx.
  • Stubbing – Used to provide a dependency for unit testing with predetermined answers and behaviour. See http://en.wikipedia.org/wiki/Test_stubs.

Jeremy Miller also writes a series called Patterns in Practice for MSDN Magazine (see list at http://msdn.microsoft.com/en-au/magazine/cc720886.aspx). They are all a good read, especially:

• Cohesion and Coupling - http://msdn.microsoft.com/en-au/magazine/cc947917.aspx
• Design for Testability - http://msdn.microsoft.com/en-au/magazine/dd263069.aspx

Tools

These are tools that are good to get experience using. Most of them relate to the patterns above. There are other tools used like ReSharper, dotTrace, StyleCop, WinMerge etc, but they don’t have the up skill requirement that the following tools do.

• Reflector - http://www.red-gate.com/products/reflector/. This is a .Net assembly disassembler that has really good search and analysis tools. This is the most important development tool for me. It is as critical to my development as Visual Studio itself.
• Rhino Mocks - http://ayende.com/projects/rhino-mocks.aspx. Mocking framework for testing.
• Unity - http://www.codeplex.com/unity. Dependency Injection framework included in Microsoft Patterns and Practices Enterprise Library.
• PostSharp - http://www.postsharp.org/. Used for AOP.
• MSTest – Unit testing integrated into Visual Studio.

Probably the most important tool to start using is Rhino Mocks. The only way to get experience with it is to start writing unit tests in VS. See the documentation at http://ayende.com/wiki/Rhino+Mocks+Documentation.ashx.

Tags: Useful Links, unity, resharper, unit testing, postsharp, aop, Performance, StyleCop, dependency injection, ReSharper, Unit Testing, PostSharp, AOP, performance, Dependency Injection

The Commentor extension for BlogEngine.Net written by rtur is a great extension for catching comment spam on the blog. Unfortunately the custom rules you can apply to comments only support a Block or Allow action.

What I want is to prevent the comments being saved at all if a manual rule has been violated. This is better for my needs as I don’t need to clean up the comments on the blog and I don’t get hassled by constant emails regarding comments that require moderation.

The changes to the extension to support this are relatively minor.

First is a change to the User controls\Commentor\Settings.aspx user control. The action dropdown now has a Delete action.

<td>
    <asp:DropDownList ID="ddAction" runat="server">
        <asp:ListItem Text="Block" Value="Block" Selected=true></asp:ListItem>
        <asp:ListItem Text="Allow" Value="Allow" Selected=false></asp:ListItem>
        <asp:ListItem Text="Delete" Value="Delete" Selected=false></asp:ListItem>
    </asp:DropDownList>
</td>

The next set of changes were to implement the Delete action in the App_Code\Extensions\Commentor.Community Server class.

The ManualFilter enum definition has been extended to include the Delete action.

private enum ManualFilter { None, Block, Allow, Delete }

The Post_AddingComment method now supports this enum value in its processing of a new comment.

// validate against filter
switch (CheckFilter(comment))
{
    case ManualFilter.Block:
        comment.IsApproved = false;
        return;
    case ManualFilter.Allow:
        comment.IsApproved = true;
        return;
    case ManualFilter.Delete:
        comment.IsApproved = false;
        e.Cancel = true;
        return;
    default:
        break;
}

And finally, the CheckRow method has been updated to use the new Delete action.

if (match)
{
    if (action == "Block")
        return ManualFilter.Block;
    if (action == "Delete")
        return ManualFilter.Delete;
    return ManualFilter.Allow;
}

Make these changes and you will be able to use delete actions to prevent comments from being saved.

NOTE: The settings for existing rules will need to be updated where they are stored (most likely in a database or xml file) in order for them to use the Delete action. A restart of the website will be required to pick up these changes that were made directly against the settings datastore. Alternatively you will need to delete and recreate any existing custom rules that you want to use the Delete action with.

My Commentor extension settings now look like the following.

Tags: blogengine.net, blogengine.net, BlogEngine.Net

Just like Reflector, SubMain has just acquired GhostDoc and has released an updated version. Looks like SubMain has already put in a decent amount of effort for GhostDoc. This is appears to be significantly different in contrast to what Red Gate has published for Reflector. Looks like it will be interesting times ahead for these tools.

Tags: ASP.Net

As I was writing and using my custom GhostDoc rules (here and here), I was thinking that it would be nice if GhostDoc was able to clear the existing documentation and then apply the DocumentThis command. I emailed Roland Weigelt about the feature idea not realising there is a forum for feature requests. He quickly replied saying that the feature is already there albeit undocumented. This is exactly what I was after.

If you open up the keyboard bindings and do a search for GhostDoc, you will find a RebuildDocumentation command.

I have assigned the RebuildDocumentation to a Ctrl+Shift+D, Ctrl+Shift+R combination and changed DocumentThis to Ctrl+Shift+D, Ctrl+Shift+D combination. Roland said to make sure that the new keyboard binding is only used in Text Editor (as highlighted above).

Tags:

To follow up on my last post about documenting unit test methods with GhostDoc, a similar concept can be applied to documenting unit test classes.

Add a custom rule under the Classes section in the GhostDoc configuration dialog.

I have used the name "Matches unit test class" and identified type names that end with "Tests". I have entered the summary documentation with the following value:

The $(TypeName.ShortNameAsSee)
class is used to test the <see cref="$(TypeName.Words.Verbatim.ExceptLast)" /> class.$(End)

This produces much nicer documentation that the default documentation provided by Visual Studio.

Tags:

GhostDoc is one of the coolest tools around for Visual Studio. Sometimes it needs a little help though and unit test methods are a classic example. The format of my unit test method names usually identifies the method name, parameter list, parameter value conditions, expected outcome and end in "Test". The default rule that GhostDoc applies to this format is fairly ugly.

For example,

/// <summary>
/// Creates the returns cache store instance test.
/// </summary>
[TestMethod]
[Description("Black box tests")]
public void CreateReturnsCacheStoreInstanceTest()
{
    ICacheStore actual = CacheStoreFactory.Create();
 
    Assert.IsNotNull(actual, "Create failed to return an instance");
}

Creating a custom GhostDoc rule for unit test methods can assist in cleaning the documentation up a little.

First, open up the GhostDoc configuration.

Under methods, click Add.

Click Ok.

Enter the new rule name, identify that the method name must end in "Test" and fill out the summary using the value "Runs test for $(MethodName.Words.ExceptLast).".

Using this new rule, the example above now gets the following documentation generated.

/// <summary>
/// Runs test for create returns cache store instance.
/// </summary>
[TestMethod]
[Description("Black box tests")]
public void CreateReturnsCacheStoreInstanceTest()
{
    ICacheStore actual = CacheStoreFactory.Create();
 
    Assert.IsNotNull(actual, "Create failed to return an instance");
}

It's not perfect, but its a lot better.

Tags:

Ah, this is great news. A new version of CopySourceAsHtml (CSAH) has just be released with support for VS2008 after a long hiatus. CSAH is a must Visual Studio addin for any developer blogger. Get the goods here.

Tags:

Here is a little tip I forgot the other day (and it did shoot me in the foot). If you are changing the BlogEngine.Net data source directly, don't forget to recycle the application. This is because BlogEngine.Net holds blog data in memory. You will be working with stale data if you change the data source and use the application without restarting it.

Tags: BlogEngine.Net

I have previously posted about using the include element for my XML documentation in cases where there is duplicated content. After a recent code review, the reviewer commented that the include element made it difficult to read the documentation because large parts of the XML documentation were abstracted out to an XML file. This made me look at ways around this and the affect of the include tag had on the tooling support.

As a quick overview, the include element in XML documentation tells the compiler to go to the specified XML file and run an XPath query (recursively). It pulls in the result of that XPath query and injects the content into the XML documentation being generated for a code element.

Advantages

• Documentation reuse
• Removes noise in a code file if the bulk of the documentation points to an included reference

Disadvantages 

• Hard to read the documentation when looking at the source
• Current ReSharper 4.1 doesn't correctly walk the include path references to validate using directives
• ReSharper 4.1 doesn't walk the include path references for intellisense (summary and param elements and their content)
• Visual Studio doesn't walk the include path references for intellisense (summary and param elements and their content and exception elements - Visual Studio ignores exception element content)
• Current StyleCop 4.3 doesn't correctly walk the include path references to validate documentation structure and content

Guidance

There is a tug of war between the reducing noise advantage and the readability disadvantage so the decision between the two must be made with respect to the code and its readers/consumers.

The disadvantages listed are primarily regarding the tooling support. With the issues stated for Visual Studio and ReSharper, they are only issues for when the interpretation of the XML documentation is done from the source directly (meaning intellisense within the same solution), rather than the compiler generated XML documentation file. The StyleCop issue is a bigger disadvantage especially if you are using the tool for strict validation as part of a continuous integration process.

To satisfy all but the readability disadvantage, I suggest that you avoid using an include to:

1. Define XML documentation structure required by StyleCop (summary, param and returns elements)
2. Define content that affect StyleCop validation (summary, param and returns elements)
3. Define XML documentation structure parsed by Visual Studio intellisense (exception element)
4. Define content that affect Visual Studio and ReSharper intellisense (summary, param and returns elements)

The include element is very useful for moving remarks and code examples out of the code file to reduce noise. When reading the code file, these items are not normally required for the readability of the file and don't affect intellisense.

Note: The StyleCop issues should be fixed in the next version. There is no indication about intellisense fixes to Visual Studio or ReSharper. The use of the include element may change as these issues are fixed.

Tags: StyleCop, ReSharper

StyleCop is a great tool for keeping code style consistent. I don't agree with all of the default rules though. Rules that you don't want can be disabled using a Settings.StyleCop file. By default, each project will use its own settings file. Having to maintain a settings file for each project is very cumbersome. Thankfully, there is a better way.

The Source Analysis blog has a post about how settings are inherited from parent directories. This makes sharing settings between projects very easy. Here are some ideas for how to set this up and make the settings file easy to work with.

These instructions assume that all the projects in the solution are in child directories under the location that the solution file resides in.

How to manage your StyleCop settings

If a Settings.StyleCop file doesn't already exist, right-click on a project and select StyleCop Settings. Remove any of the rules that you don't want applied and click OK.

Open Windows Explorer for that project and move the Settings.StyleCop file into the parent (solution) directory.

Right-click on the solution in Solution Explorer and select Add -> Existing Item.

Select Settings.StyleCop from the solution directory.

This will add a link to this file into the solution, but not specific to a project. For example:

The next step is to ensure that the default application for this file in Visual Studio is the StyleCop settings editor.

Right-click the Settings.StyleCop file and select Open With.

Ensure that StyleCopSettingsEditor is set as the default. If it isn't, select it and click Set as Default and click OK.

From now on, you can simply open the Settings.StyleCop file like any other file and it will open up in the settings.

Note: Using this configuration, don't edit the settings for StyleCop against the project directly as these settings will not be available to the other projects in the solution.

This is my current settings file: Settings.StyleCop (2.94 kb)

Tags: StyleCop, Extensibility