Coding Standards

On 27 Sep 2010, chefkoch suggested that this page or content is incomplete and needs to be expanded with information on using Visual Studio and ReSharper templates with links to these.

IMPORTANT: Header

As we are an open source project every file in SVN needs the copyright header. Please copy that header paragraph to the beginning of each document. You can copy the current header from another file in MediaPortal 1/ MediaPortal 2 and you find it in the templates in the MediaPortal 2 source tree.

The header looks like this (most probably with a newer year as typically our devs forget to change this wiki page):

Sample of a C# file header:

#region Copyright (C) 2005-2010 Team MediaPortal

// Copyright (C) 2005-2010 Team MediaPortal
// http://www.team-mediaportal.com
// 
// MediaPortal is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 2 of the License, or
// (at your option) any later version.
// 
// MediaPortal is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// 
// You should have received a copy of the GNU General Public License
// along with MediaPortal. If not, see <http://www.gnu.org/licenses/>.

#endregion

#region Copyright (C) 2007-2010 Team MediaPortal

/*
    Copyright (C) 2007-2010 Team MediaPortal
    http://www.team-mediaportal.com

    This file is part of MediaPortal 2

    MediaPortal 2 is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    MediaPortal 2 is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with MediaPortal 2.  If not, see <http://www.gnu.org/licenses/>.
*/

#endregion

C# source

Keep your classes/files short, don't exceed 2000 LOC, divide your code up, make structures clearer. Put every class in a separate file and name the file like the class name (with .cs as extension of course). This convention makes things much easier.

IMPORTANT: Indentation

Setup Visual Studio to use 2 spaces as indentation and use Automatic Formatting regularly

In Microsoft Visual Studio this can be set via Tools (Menu) -> Options -> Text Editor -> C# -> Tabs

(tab size = 2, indent size = 2, Insert spaces)

In VS Express this can be set via Tools (Menu) -> Options -> Text Editor -> C# -> Tabs

(tab size = 2, indent size = 2, Insert spaces)

Make sure the Show all settings box is checked.

Auto Formating in both VS 2005 and Express is done via Edit (Menu) -> Advanced -> Format Document

Code Comments

There is an own Wiki entry describing the way of documenting the code.

Declarations

One declaration per line is recommended since it encourages commenting.

int level; // indentation level
int size; // size of table

Do not put more than one variable or variables of different types on the same line when declaring them.

Example:

int a, b; //What is 'a'? What does 'b' stand for?

The above example also demonstrates the drawbacks of non-obvious variable names. Be clear when naming variables.

Class and Interface Declarations

When coding C# classes and interfaces, the following formatting rules should be followed:

• No space between a method name and the parenthesis " (" starting its parameter list.
• The opening brace "{" appears in the next line after the declaration statement
• The closing brace "}" starts a line by itself indented to match its corresponding opening brace.

Example:

Class MySample : MyClass, IMyInterface
{
  int _myInt;
  public MySample(int myInt)
  {
    _myInt = myInt;
  }
  void Inc()
  {
    ++_myInt;
  }
  void EmptyMethod()
  {
  }
}

For a brace placement example look at section 10.1.

The order of regions inside a class should be:

public class Template_Class
{
  #region Imports
  #endregion

  #region Enums
  #endregion

  #region Delegates
  #endregion

  #region Events
  #endregion

  #region Variables
  // Private Variables
  // Protected Variables
  // Public Variables
  #endregion

  #region Constructors/Destructors
  #endregion

  #region Public properties
  // Public properties
  #endregion

  #region Public methods
  #endregion

  #region Private methods
  #endregion

  #region Base overrides
  #endregion

  #region Interface implementations
  // region for each interface
  #endregion
}

This Regions layout is included in a Visual Studio code snippet that is helpfully attached here: Regions-outline.snippet

If, if-else, if else-if else Statements

if (condition)
{
  DoSomething();
  ...
}
if (condition)
{
  DoSomething();
  ...
}
else
{
  DoSomethingOther();
  ...
}
if (condition)
{
  DoSomething();
  ...
}
else if (condition)
{
  DoSomethingOther();
  ...
}
else
{
  DoSomethingOtherAgain();
  ...
}

For / Foreach Statements

A for statement should have following form:

for (int i = 0; i < 5; ++i)
{
  ...
}

or single lined (consider using a while statement instead):

for (initialization; condition; update);

A foreach should look like:

foreach (int i in IntList)
{
  ...
}

While/do-while Statements

A while statement should be written as follows:

while (condition)
{
  ...
}

An empty while should have the following form:

while (condition);

A do-while statement should have the following form:

do
{
  ...
} while (condition);

Switch Statements

switch (condition)
{
  case A:
  ...
  break;
  case B:
  ...
  break;
  default:
  ...
  break;
}

Try-catch Statements

A try-catch statement should follow this form:

try
{
  ...
} catch (Exception)
{
  ...
}
finally
{
  ...
}

White space

TestMethod(a, b, c);

TestMethod(a,b,c)

a = b; // don't use a=b;
for (int i = 0; i < 10; ++i) // don't use for (int i=0; i<10; ++i)
// or
// for(int i=0;i<10;++i)

Naming Conventions

public class Math
{
  public const PI = ...
  public const E = ...
  public const FeigenBaumNumber = ...
}

Naming Guidelines

Generally the use of underscore characters inside names and naming according to the guidelines for Hungarian notation are considered bad practice.

Hungarian notation is a defined set of pre and postfixes which are applied to names to reflect the type of the variable. This style of naming was widely used in early Windows programming, but now is obsolete or at least should be considered deprecated. Using Hungarian notation is not allowed if you follow this guide.

A good variable name describes the semantic not the type.

An exception to this rule is GUI code. All fields and variable names that contain GUI elements like button should be postfixed with their type name without abbreviations. For example:

System.Windows.Forms.Button cancelButton;
System.Windows.Forms.TextBox nameTextBox;

Programming Practices

public class MyMath
{
  public const double PI = 3.14159...
}

namespace ShowMeTheBracket
{
  public enum Test
  {
    TestMe,
    TestYou
  }

  public class TestMeClass
  {
    Test _test;
    public Test Test
    {
      get
      {
        return _test;
      }
      set
      {
        _test = value;
      }
    }

    void DoSomething()
    {
      if (_test == Test.TestMe)
      {
        //...stuff gets done
      }
      else
      {
        //...other stuff gets done
      }
    }
  }
}

for (int primeCandidate = 1; primeCandidate < num; ++primeCandidate)
{
  isPrime[primeCandidate] = true;
}

for (int factor = 2; factor < num / 2; ++factor)
{
  int factorableNumber = factor + factor;
  while (factorableNumber <= num)
  {
    isPrime[factorableNumber] = false;
    factorableNumber += factor;
  }
}

for (int primeCandidate = 0; primeCandidate < num; ++primeCandidate)
{
  if (isPrime[primeCandidate])
  {
    Console.WriteLine(primeCandidate + " is prime.");
  }
}

References

Design Guidelines for Class Library Developers