Binarymist

This is the current set of coding standards and guidelines I use when I’m coding in the C#.NET language.
I thought it would be good to share so others could get use out of them also, and maybe start a discussion as to amendments / changes they see that could be useful?

• Naming Conventions
• Coding Style
  • Commenting
    • Comment Style
    • XML Documentation
  • File Organisation
  • Formatting
    • Bracing
    • Spacing
    • Tabs and Indenting
• Language Usage
  • Access Modifiers
  • Calling Routines
  • Class
  • Events, Delegates
  • Exceptions
  • Flow Control
    • Case Statements
    • Conditions
  • Implicit typing using the Var keyword
  • Namespace
  • Variables and Types
    • Strings

Naming Conventions

• Do not use Hungarian notation, I.E. a boolian variable may have the name MyBool, but shouldn’t be called bMyBool.
• Do prefix member variables with the underscore ‘_’. Do not prefix member variables with “this”. also use camelCasing for member variables. The underscore is easy to see, is one key stroke.
• Do prefix interfaces names with “I”
• Do not prefix enums, classes, or delegates with any letter.

Key:

“c” = camelCase
“P” = PascalCase
“_” = Prefix with _Underscore
“x” = Not Applicable.

Coding Style

Commenting

Comment Style

Block comments should usually be avoided

/* Line 1
* Line 2
* Line 3
*/

/* … */

Begin comment text with an upper case character. End comment text with a period.

If you have to comment your code, consider refactoring, so that it is easier to read.
Prefer not to use inline-comments to explain obvious code. Well written code is self-documenting.
Rather fix or clean up code now, than put a // Todo in.

You can access // Todo‘s in Visual Studio via

View menu -> Task List
The Tokens can be setup in Tools -> Options… -> Environment->Task List

or for ReSharper

ReSharper menu -> Tools -> To-do Items (or use the key shortcuts)

Use the following tokens:

• Todo
• Note
• Bug
• Not Implemented

XML Documentation

• Always apply C# comment-blocks (///) to public, protected, and internal declarations.
• Only use C# comment-blocks for documenting the API I.E the interface.
• include <summary> comments. Include <param>, <return>, and <exception> comment
  sections where applicable.
• Include <see cref=””/> and <seeAlso cref=””/> where possible.
• Always add CDATA tags to comments containing code and other embedded markup in order to avoid
  encoding issues.
  Example:

  ///
  /// Add the following key to the appSettings” section of your config:
  /// <code><![CDATA[
  ///   <configuration>
  ///     <appSettings>
  ///       <add key=”mySetting” value=”myValue”/>
  ///     </appSettings>
  ///   </configuration>
  /// ]]></code>
  ///
  

File Organisation

Group internal class implementation by type in the following order:

1. Member variables.
2. Constructors & Finalizers.
3. Nested Enums, Structs, and Classes.
4. Properties
5. Methods

Sequence declarations within type groups based upon access modifier and visibility:

1. Public
2. Protected
3. Internal
4. Private

• Do not use #region statements
• Always match class name and file name where ever possible. Avoid including more than one class per file.

Formatting

Bracing

• Place first brace of the block at the end of the line preceded with a space.
  In languages like C, C++, C#, Java, it doesn’t matter where you put the first curly brace, it’s just personal preference or based on vote.
  In languages like JavaScript, it does matter. I use quite a bit of JavaScript, so just find it easier to use the same convention. Although at work, we use the “opening brace on a new line convention, simply because it won the vote”.
• Always use curly braces ({ and }) in conditional statements. Unless there is a very simple statement, like return bla.
• Recursively indent all code blocks contained within braces.

Spacing

Use white space (CR/LF, Tabs, etc) liberally to separate and organize code.

Only declare related attribute declarations on a single line, otherwise stack each attribute as a separate declaration.

Example:

// Bad!
[Attrbute1, Attrbute2, Attrbute3]
public class MyClass {
   …
}

// Good!
[Attrbute1, RelatedAttribute2]
[Attrbute3]
[Attrbute4]
public class MyClass {
   …
}

Tabs and Indenting

Tab characters (x09) should not be used in code. All indentation should be done with 3 space characters.

Language Usage

Access Modifiers

Do not omit access modifiers.
Explicitly declare all identifiers with the appropriate access modifier instead of allowing the default.
Example:

// Bad!
Void WriteEvent(string message) {
   …
}

// Good!
private Void WriteEvent(string message) {
   …
}

	Both the above definitions are private.
	Prefer explicit to implicit.

Calling Routines

When calling a routine that takes a bool or a number.
Don’t pass litterals, as it’s unclair what they represent.
Instead create a variable with a meaningful name.

// calling MethodTakingExampleArgs
MethodTakingExampleArgs(true, 12);

// instead do the following

bool temperatureHasChanged = true;
int temperatureInCelcius = 12;

// calling MethodTakingExampleArgs
MethodTakingExampleArgs(temperatureHasChanged, temperatureInCelcius);

The intent becomes clearer, thus making for code that’s easier to read, thus we work faster.

If a routine call has its parameters spread over more than a single line due to being to long, place each parameter on its own line.
Also consider how many arguments are being passed, if it’s over 5, consider other ways to pass the information needed.

Class

Avoid putting multiple classes in a single file.

Events, Delegates

The delegate type should be prefixed with “Handler”.
The name of the procedure that does the work should be a verb.

public class MyDelegateExample {
   delegate void ChangeHandler();
   event ChangeHandler _change;

   private void OnChange() {
      if (_change != null)
         _change();
   }
}

	Rather than checking for null, you can add an empty delegate to your _change event
	so that you don’t have to check the event for null before you raise it.

The traditional null check followed by the next action is not atomic, so not thread safe. Discussed in more depth here.

public class MyDelegateExample {

   delegate void ChangeHandler();
   event ChangeHandler _change = delegate{};

   public void Attach(ChangeHandler update) {
      Change += update;
   }

   public void Detach(ChangeHandler update) {
      Change -= update;
   }

   private void OnChange() {
      _change();
   }
}

Exceptions

• Do not use try/catch blocks for flow-control. Only use for exceptional cases.
• Only catch exceptions that you can handle.
• Never declare an empty catch block.
• Avoid nesting a try/catch within a catch block.
• Always catch the most derived exception via exception filters.
• Order exception filters from most to least derived exception type.
• Avoid re-throwing an exception. Allow it to bubble-up instead.
• If re-throwing an exception, preserve the original call stack by omitting the exception argument from the throw statement.Example:

  // Bad!
  catch(Exception e) {
     Log(e);
     throw e;
  }
  
  // Good!
  catch(Exception e) {
     Log(e);
     throw;
  }
  

• Only use the finally block to release resources from a try statement.
• Always use validation to avoid exceptions.
  Example:

  // Bad!
  try {
     conn.Close();
  }
  Catch(Exception ex) {
     // handle exception if already closed!
  }
  
  // Good!
  if(conn.State != ConnectionState.Closed) {
     conn.Close();
  }
  

• Always set the innerException property on thrown exceptions so the exception chain & call stack are maintained.
• Avoid defining custom exception classes if there is an existing Exception derived class available in the .NET library.
• Always suffix exception class names with the word “Exception”.
• Always add the SerializableAttribute to exception classes.
• Always implement the standard “Exception Constructor Pattern”:

  public MyCustomException ();
  public MyCustomException (string message);
  public MyCustomException (string message, Exception innerException);
  

  Or better… if using .NET 4.0 or greater, use optional parameters.

• Always implement the deserialization constructor:

  protected MyCustomException(SerializationInfo info, treamingContext contxt);
  

Flow Control

Case Statements

• Only use switch/case statements for simple operations with parallel conditional logic.
• Prefer nested if/else over switch/case for short conditional sequences and complex conditions.
• Prefer polymorphism over switch/case to encapsulate and delegate complex operations.
  Don’t fall into the trap of writing procedural code in an OO language.

Conditions

Avoid evaluating Boolean conditions against true or false.
Example:

// Bad!
if(isValid == true) {
   …
}

// Good!
if(isValid) {
   …
}

Use braces {} as shown above in all situations but for the most simple.
If you have more than a single line statement in a conditional, surround it with braces.

Implicit typing using the var keyword

Some background on var:

The compiler simply takes the compile time
type of the initialization expression and makes the variable have that type too.
An example:

var stringVariable = "Hello, world."
stringVariable = 0;

The above code is invalid.

The var keyword should only be used with LINQ and Anonymous types.
Unless there’s a significant gain in code simplicity, use explicit typing.

It is recommended to use var only when it is necessary, that is, when the variable will be used to store an anonymous type or a collection of anonymous types.
See Microsofts reference on var.

Sometimes you actually want the code to break when a type is changed.

Consider a control system. Many elements have On() and Off() methods. there are many cases where there is no relationship between the types (i.e. no common base classes or interfaces), there is only the similarity that both have methods with those signatures.

Writting code:

var thing = SomeFactory.GetThing();  // Returns something that is safe to turn off...
thing.Off();

Then later a change is made to the Factory and that method now returns something completely different, which happens to have severe consequences if it is arbitrarily turned off having such a design is debatable for many reasons.

By using var, the previous code will compile without complaint. Even though the return type may have changed from ReadingLamp to LifeSupportSystem.

I believe that there are more times when there is the possibility of an “unintended side-effect” caused by a change in the type than there are times where the change in type has no bearing on the code that consumes it. As a result, I very rarely use var. Even when the return type is obvious (such as the LHS of a new), I find it easier to be consistent.

Namespace

• CompanyName.SolutionDescription.AssemblyDescription
• Never declare more than 1 namespace per file.
• Append folder-name to namespace for source files within sub-folders.
• Also see the Naming conventions table.
• Place namespace “using” statements together at the top of file. Group .NET namespaces above custom namespaces.
• Followed by grouping of external namespaces.
• Followed by grouping of organisation namespaces.
• Order namespace “using” statements alphabetically.

Variables and Types

• Declare and preferably initialize local variables at the same point and as close to where you first use them.
• Always choose the simplest data type, list, or object required.
• Always use the built-in C# data type aliases, not the .NET common type system (CTS).
  Example:

	short NOT System.Int16
	int NOT System.Int32
	long NOT System.Int64
	string NOT System.String

• Declare one variable per line.
• Only declare member variables as private. Use properties to provide access to them with public, protected, or internal access modifiers.
• Prefer to use the as operator and check for null, rather than directly casting, and having to handle potential InvalidCastException.

  object dataObject = LoadData();
  DataSet ds = dataObject as DataSet;
  if(ds != null) {
     …
  }
  

• Avoid boxing and unboxing value types.
  Especially in loops, or where performance matters.Example:

  int count = 1;
  object refCount = count; // Implicitly boxed.
  int newCount = (int)refCount; // Explicitly unboxed.
  

Strings

• Use the “@” prefix for string literals instead of escaped strings.
• Prefer String.Format() or StringBuilder over string concatenation.
  StringBuilder performs many times faster (thousands in fact)
• Never concatenate strings inside a loop. Remember, string’s are immutable. Each time you concatenate, a new instance of string is created.
• Checking whether a string is empty?
  String.Length == 0 or “” is faster than String.Empty, but… beware of null strings, if null when you perform a String.Length, you’ll get a NullReferenceException.
  The safest technique is to use the static IsNullOrEmpty function on string.
  Using “” does not create a new object. Due to string interning, it will be created either once per assembly or once per AppDomain.