Software Development Guidelines to Live By

Not too long ago I posted a tweet that immediately went viral. (OK, it’s all relative – to me 66 retweets and 120 favorites is viral.)  It referred to Microsoft’s Engineering Guidelines for contributing to its open-source repository on GitHub for the next version of its web development platform, ASP.NET 5.
 
 
 
 
 
 
 

You may be familiar with other C# Coding Guidelines.  And generally I’m a huge fan of picking a set of guidelines, making necessary adjustments, and sticking to them as a team.  But what I appreciate about the ASP.NET 5 guidelines is that they not only cover coding guidelines, but also include other vital aspects of software development, such as source code management, product planning and issue tracking.

One of the first things listed is the guidelines for submitting pull requests and a description of how they are reviewed and approved (using an emoticon!).  Their Git branching strategy is also described, as well as the solution and project folder structure and the assembly naming pattern.  It’s notable that xUnit is used for all testing and is indicative that xUnit has now supplanted both MSTest and NUnit as the preeminent testing platform.  (In other words, just use it.)  It’s also worth noting that to use xUnit you no longer need to install a Visual Studio extension – adding the xUnit NuGet package is all you need to do for tests to show up in the Visual Studio Test Explorer.  And ReSharper has its own xUnit plugin, which you can install to use the R# test runner with xUnit tests.  Lastly, you’ll want to pay close attention to the naming guidelines for test assemblies, classes and methods, as well as appropriate unit test structure, and taking into account exception messages in your tests.

The actual coding guidelines section is rather lightweight, probably because ReSharper enforces most generally accepted rules.  (You are using ReSharper, aren’t you?!)  If you’re a company, the commercial license is well worth the price, but if you’re an individual developer and price is a concern, see if you can qualify for a free license as the author of an open source project.  One interesting thing to call out is the use of the [NotNull] parameter attribute for argument null checking, which results in null-checking code injected into the method at compile-time.  You’ll need to use it on all public methods, including constructors and property setters.

Another thing to note is the restricted use of internal types and members.  You’ll almost always want to shy away from the use of internal and instead place those types in a namespace which indicates they are primarily for internal use.  It’s not a hard and fast rule, but it’s how most modern frameworks are built.  This makes the use of the [InternalsVisibleTo] attribute unnecessary, which is good because it prevents you from having to modify a core assembly when all you want to do is add a test assembly for it.

The most controversial part of the coding guidelines is the recommendation to use the var keyword whenever possible for local type inference.  I have mixed feelings on this one, because nowadays you’re often looking at code in GitHub, or with a Git client, where you can’t just mouse over var for the return of a method call to see what the type really is.  On the other hand, there are arguments for using var whenever allowed by the compiler.  For this one, it’s really a matter of what your team prefers.

Note that guidelines are only as effective as their enforcement.  For this reason, you’ll need something like StyleCop, which has been implemented as a ReSharper extension.  First install it by selecting Extensions Manager from the ReSharper menu in Visual Studio.

Then go to ReSharper, Options, Tools, and select StyleCop.  If you see a compatibility warning message, click the the button that says, “Reset C# Code Style Options.”

After this, you’ll see StyleCop rules pop up when you’ve violated standard conventions, such as the ordering of using directives. In the example below, selecting the first option will reorder the usings appropriately.

There are also facilities which allow you to select a Settings.StyleCop file, and to enable the  insertion of file headers during cleanup.

The last thing I’ll mention is that there is an unwritten rule regarding line length: lines of code should not be so long as to cause the scroll bar to appear in GitHub.  I found this to happen when exceeding 118 characters, but you may wish to limit your code to a shorter width.  Whatever length you decide on, you need a visual cue for when your code has exceeded it.  The best way I know if is to install the Visual Studio Productivity Power Tools, and insert a registry entry so that a vertical guideline will appear showing where to insert a line break.

The AspNet guidelines are a step in the right direction, but there are a bunch of other things developer should keep in mind when writing code.  In particular, when refactoring one should avoid code smells as much as possible.  These coding standards provide a nice summary, and they mention the principles of SOLID, KISS, YAGNI and DRY, as well as common design patterns.

The important thing is not to take these guidelines as written in stone, but as a starting point for formulating your own set of guidelines, which work for you, your project and your team.