Features Screenshots ProjectSetup CodingStandards CodeAnalysis DesignStandards UnitTesting CodeSnippets

Coding Standards

A comprehensive coding standard is essential for successful product delivery. The standard helps to enforce best practices and avoid pitfalls. It also provides a means for developers to “feel at home” no matter what or whose code is being looked at.

Many of the standards defined in this document will be supported by a coding standards tool which automatically checks source code against a list of rules. For some standards, it will be up to the reviewer of the code to determine whether the standards are met. These are not necessarily hard and fast rules but rather strongly suggested guidelines meant to make developers aware of key areas of concern regarding writing code. It is “OK” to go beyond the limits of these standards but the developer should at least stop and reconsider before proceeding. Reviewers should also raise questions when standards are not met and discuss them with the developer.

To help us meet these standards we use a code analysis tool called StyleCop. You can download this tool and any additional rules as well as view the install instructions here CodeAnalysis.

Naming Conventions and Style

Use Pascal casing for class names.

public class DataSource
{
}

Use Pascal casing for method names and properties.

public class Calendar
{
    private int NumberOfDays { get { return _numberOfDays; } }
    private void ValidateDaysInMonth()
    {...}

    public string Month { get { return _month; } } 
    public void Initialize() 
    {...}
}

Prefix interface names with I and use Pascal casing.

public interface IMyInterface
{
}

Use Pascal casing for enumerations.

public enum FileOperations
{ 
    Create,
    Open,
    CreateAndOpen
}

Prefix private fields (data members) with _ and use camel casing.

public class DataSource
{
    private string _fileName;
}

Avoid declaring public and protected fields. Use properties instead.

Use Pascal case for read only or const fields that are public.

public class Calendar
{
    public readonly int MaxCount = 3;
    public const int DaysPerWeek = 7;
}

Use _camel case for read only and const fields that are protected or private. Note that this follows field casing conventions.

public class Calendar
{
    protected const int _daysPerWeek = 7;
}

Use camel casing for arguments and local variables.

public class Calendar
{
    public void Initialize(string month) 
    {
        int daysInMonth = ComputeNumberOfDays(month);
    }
}

Avoid using Hungarian notation.

Use nouns or noun phrases for class names.

public class Calendar
{
}

public class CalendarProvider
{
}

Use nouns, noun phrases or adjectives for interface names.

public interface ICalendar
{
}

public interface ICalendarProvider
{
}

public interface IPersistable
{
}

Suffix custom exception classes with Exception.

public class AmplifierException : Exception
{
}

Suffix custom event args classes with EventArgs.

public class AmplifierEventArgs : EventArgs
{
}

Use verbs when naming events.

public class Class1
{
    public event EventHandler Open;
}

Avoid using On as a prefix in event handlers.

void OpenClick(object sender, EventArgs e)
{
    MessageBox.Show("Open button was pressed");
}

Use braces on all if statements. Optional if single line return or throw statement is used.

public void ValidateDataSource()
{
    if (_dataSource.IsLocal)
    {
        ValidateLocalDataSource();
    }
    else
    {
        ValidateRemoteDataSource();
    }
}

Use braces on all for, foreach, while and other looping constructs.

Explicitly state public, internal, protected and private access modifiers. Note that classes default to internal and properties, methods, etc. default to private.

internal class Calendar
{
    private string _month;
}

Coding Practices

Use properties if they exist when writing class implementation code.

public class EEGSetupInfo
{
    #region Non Public Members
    private string _eegTestName;
    private void Serialize()
    {
        string key = EEGTestName;
    }
    #endregion

    public string EEGTestName { get { return _eegTestName; } }
}

Use const directive only on natural constants such as the number of days in a week, pi, inches in foot, etc. Use readonly for values that have the possibility of changing.

Use enumerations, const and read only fields instead of literals.

private enum Columns
{
    Name = 0,
    Date = 1,
    Size = 2
}

private void InitializeDisplay()
{
    _fileList.Columns[Columns.Name].Text = "Name";
    _fileList.Columns[Columns.Size].Text = "Size";
    _fFileList.Columns[Columns.Date].Text = "Date";
    ...
}

Avoid putting multiple classes, interfaces, or a combination of the two in a single file. Nested classes are the exception.

Consider refactoring if a class has more than 750 lines.

Consider refactoring if a method has more than 50 lines.

Use inline comments where needed.

Avoid comments that explain the obvious. Code should be self-explanatory. Good code with readable variable and method names should minimize the need for comments.

Provide xml documentation headers for all class, fields, methods, interfaces, and properties.

List what exceptions can be thrown (explicitly) by the method or property.

/// <summary>
/// Loads file info from SourceDirectory
/// </summary>
/// <exception cref="DirectoryNotFoundException">Thrown if the source directory does not exist</exception>
public void Initialize()
{
    if (!SourceDirectory.Exists)
    {
        throw new DirectoryNotFoundException();
    }
    ...
}

Use a // TODO: comment for code that needs to be completed. Before release we will check for any // TODO: comments and resolve them. Include initials and date.

public void RunAnalysis()
{
    // TODO: MS 2/10/2008: We need to verify how well
    // this algorithm works before release
    ...
}