Coding Standards

Coding Standards

##Formatting

####Conditional Blocks

• All conditional blocks should be enclosed in curly brackets. If a block is a one word statement, such as return, it can be placed on the same line.

// Acceptable...
if(something) return;

if(something)
{
  return;
}

//Not acceptable...
if(something)
  return;

####Const

• Magic numbers should be avoided. Mark values as const and name them according to the MSDN Capitalization Conventions

##Documentation

Beyond correctness, there is nothing more important to our codebase than MAINTAINABILITY. If another developer can't understand your code and it's not commented, it could very well get ripped out for no good reason. Let's prevent that from happening by writing good comments.

So, all developers are expected to comment their code. Note, in Visual Studio typing "///" on the line above a method will make Visual Studio automatically outline your comments.

####Inline Comments

Use common sense. If the block of code you're writing is obstruse or does a lot in one line, consider commenting it. A good example are dense LINQ calls.

####Class definition

For each method, provide the following:

• Summary - The summary describes the purpose of the class and basic implementation details.

Here's an example

/// <summary>
///     Manages instantiation of custom nodes.  All custom nodes known to Dynamo should be stored
///     with this type.  This object implements late initialization of custom nodes by providing a 
///     single interface to initialize custom nodes.  
/// </summary>
public class CustomNodeLoader {
...
}

####Class Properties

For properties, provide the following:

• Summary
• A description of what the property does

Here's an example:

/// <summary>
/// NodeNames property
/// </summary>
/// <value>Maps function names to function ids.</value>
public ObservableDictionary<string, Guid> NodeNames
{
    get;
    private set;
}

####Class methods

For each method, provide the following:

• Summary
• Descriptions for each parameter
• If applicable, a description of what the method returns.

Here's an example

/// <summary>
///     Get a node header (guid, name, category) from a given path.  This path points
///     usually to a .dyf file.
/// </summary>
/// <param name="path">The path from which to get the header/param>
/// <param name="guid">A reference to the guid (OUT) Guid.Empty if function returns false. </param>
/// <param name="name">A reference to the node name (OUT) Empty string if function returns false </param>
/// <param name="category">A reference to the category name (OUT) Empty string if function returns false </param>
/// <returns>Whether we successfully obtained the header or not.  </returns>
public static bool GetHeaderFromPath(string path, out Guid guid, out string name, out string category ) {
...
}

For zero-touch methods, it is highly recommended that you include the names of the output ports. This is discussed in more depth here.

##Testing

For all new pieces of functionality, provide unit tests.

####Framework

The Dynamo project uses NUnit for testing. Using ReSharper allows you to run unit tests directly from Visual Studio. If you don't have ReSharper, you probably should get it. Otherwise, get yourself a copy of NUnit - it's free.

####Naming

Unit tests should be placed in a separate assembly from the one you are testing and named by appending "Tests" to the project name. For example, for the "DynamoCore" project the unit test assembly is called "DynamoCoreTests." Putting unit tests in a separate assemblies allows us to omit unit tests when shipping and naming them as such allows us to easily identify those assemblies.

####Design considerations for unit-testing

If applicable, design your classes such that they can be unit-tested without needing to instantiate a large amount of other infrastructure (particularly user interfaces). This is all obvious good OOP. If you are passing DynamoModel as a reference to a method or class, you're probably doing something bad.