Framework.Guidelines.md

Framework Guidelines

Use C# type aliases instead of the types from the System namespace

For instance, use object instead of Object, string instead of String, and int instead of Int32. These aliases have been introduced to make the primitive types a first class citizen of the C# language so use them accordingly.

When referring to static members of those types, it is custom to use the full CLS name, eg) Int32.Parse() instead of int.Parse().

Properly name properties, variables or fields referring to localised resources

The guidelines in this topic apply to localisable resources such as error messages and menu text.

• Use Pascal casing in resource keys.
• Provide descriptive rather than short identifiers. Keep them concise where possible, but don't sacrifice readability.
• Use only alphanumeric characters in naming resources.

Don't hardcode strings that change based on the deployment

Examples include connection strings, server addresses, etc. Use Resources, the ConnectionStrings property of the ConfigurationManager class, or the Settings class generated by Visual Studio. Maintain the actual values into the app.config or web.config (and most definitely not in a custom configuration store).

Build with the highest warning level

Configure the development environment to use Warning Level 4 for the C# compiler, and enable the option Treat warnings as errors. This allows the compiler to enforce the highest possible code quality.

Properly fill the attributes of the AssemblyInfo.cs file

Ensure that the attributes for the company name, description, copyright statement, version, etc. are filled. One way to ensure that version and other fields that are common to all assemblies have the same values, is to move the corresponding attributes out of the AssemblyInfo.cs into a SolutionInfo.cs file that is shared by all projects within the solution.

Avoid LINQ for simple expressions

Rather than

var query = from item in items where item.Length > 0;

Prefer using the extension methods from the System.Linq namespace.

var query = items.Where(i => i.Length > 0);

Since LINQ queries should be written out over multiple lines for readability, the second example is a bit more readable.

Use Lambda expressions instead of delegates

Lambda expressions provide a much more elegant alternative for anonymous delegates. So instead of

Customer c = Array.Find(customers, delegate(Customer c) 
{ 
	return c.Name == "Tom"; 
});

use a Lambda expression:

Customer c = Array.Find(customers, c => c.Name == "Tom");

Or even better

var customer = customers.Where(c => c.Name == "Tom");

Only use the dynamic keyword when talking to a dynamic object

The dynamic keyword has been introduced for working with dynamic languages. Using it introduces a serious performance bottleneck because the compiler has to generate some complex Reflection code.

Use it only for calling methods or members of a dynamically created instance (using the Activator) class as an alternative to Type.GetProperty() and Type.GetMethod(), or for working with COM Interop types.

Favour async/await over the Task

Using the new C# 5.0 keywords results in code that can still be read sequentially and also improves maintainability a lot, even if you need to chain multiple asynchronous operations. For example, rather than defining your method like this:

public Task<Data> GetDataAsync()
{
    return MyWebService.FetchDataAsync()
                       .ContinueWith(t => new Data (t.Result));
}

Define it like this:

public async Task<Data> GetDataAsync()
{
    var result = await MyWebService.FetchDataAsync();

    return new Data (result);
}