Applicability

This applies to all Malevich code - unit tests are code as well and should follow the same style guide.

Formatting

General principles:

• Formatting is based on default Visual Studio 2008 C# formatting rules.
• Conserve vertical space.
• All languages follow C# coding conventions in spirit wherever possible.
• Above all else, keep consistent with the code around you!

Specializations over the default formatting:

• 4 space-indent, no tabs.
• Line continuations indented 4 spaces.

    Console.WriteLine("The Quick Red Fox Jumps " +
        "Over the Lazy Brown Dog.");

• No ASCII alignment, except in LINQ expressions.

// Good:
    int a;
    double b;
    float c;

// Bad:
    int      a;
    double  b;
    float   c;

// Good
    int Func(int a, int b, int c,
        double d, float e, object f)
...
    Func(1, 2, 3,
        4.5, 5.0, "hey");

// Bad
    int Func(int a,
             int b,
             int c,
             double d,
             float e,
             object f)
...
    Func(1,
         2,
         3,
         4.5,
         5.0,
         "hey");

// Good
   var linqQuery = from blah in context.Blahs
                   where blah.foo == bar
                   select blah;

• Max line length is 120 characters. You can have Visual Studio display the margin guide by putting the following in your registry:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\9.0\Text Editor]
"Guides"="RGB(192, 192, 192) 120"

• Braces go on separate lines. If a composite operator consists of two statement blocks, both must either be surrounded by braces, or not.

    if (condition)
    {
        ...several statements...
    }
...
    if (condition)
    {
        ...one statement...
    }
    else
    {
        ...several statements...
    }
...
    if (condition)
        ...one statement...
...
    if (condition)
        ...one statement...
    else
        ...one statement...

• Use parenthesis to disambiguate operator execution order.

// OK
    if (x == 1 && y == 2)
// Better
    if ((x == 1) && (y == 2))
// Bad
    bool x = a && c ? b : d && e;

• String constants should fit on one line. use addition to concatenate string constants when they have to span more than one line. Compiler inlines concatentation of string constants.

// Good
    string text = "Dear {0},\n" +
        "Please find the latest version attached.\n\n" +
        "Yours, {1}\n";
// Bad
    string text = "Dear {0},
Please find the latest version attached.

Yours, {1}
";

Naming

• Everything above function scope uses PascalCasing
• Everything at function scope and below uses camelCasing
• LINQ queries should end in "Query"

   var linqQuery = from blah in context.Blahs
                   where blah.foo == bar
                   select blah;

• In SQL code all SQL keywords are capitalized, and all function/sproc/variable/parameter names follow C# naming conventions.
• Do not use this as a prefix for accessing instance variables and methods. The casing in names is enough to disambiguate usage:

class MyClass
{
    int VarOne;
    int VarTwo;
    public MyClass(int varOne, int varTwo)
    {
// Good
        VarOne = varOne;
// Bad
        this.VarTwo = varTwo;
    }
}

Comments

• Copyrights are required for every file. Use the following template:

//-----------------------------------------------------------------------
// <copyright>
// Copyright (C) *Your Name Here* for The Malevich Project.
//
// This file is subject to the terms and conditions of the Microsoft Public License (MS-PL).
// See http://www.microsoft.com/opensource/licenses.mspx#Ms-PL for more details.
// </copyright>
//----------------------------------------------------------------------- 

• In C# XML comments are required for every type, instance variable and method, public or private.
• In Javascript, comments are required for every global or instance variable or function. Use the following as an example/template:

//
// Sends comment to server.
//
// commentId The id of the comment.
// commentString The comment itself.
function sendCommentToServer(commentId, commentString)
{
...

• Comments for methods should start with a verb in 3rd person (what the function does as opposed to telling it what to do), e.g. "Copies file A to a different directory." and not "Copy file A...".
• In SQL code, comments are required for every stored procedure. Use the following as an example/template:

-- =============================================
-- Author: Sergey Solyanik
-- Create date: 11/29/2008
-- Description: Adds or updates a comment
-- =============================================
CREATE PROCEDURE [dbo].[AddComment]
    @fileVersion int,
    ....
AS
BEGIN
...
END

Programming

• Favor code readability over efficiency and brevity.
• But brevity can sometimes enhance readability :-).
• If an Exception (the base class) is caught, it MUST be rethrown. Only catch specific exceptions if you eat them!

// Good
    try
    {
        ....
    }
    catch (SqlException ex)
    {
        Console.WriteLine(ex);
    }
// Bad
    try
    {
        ....
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex);
    }

• String concatentation is an O(N) operation. Use string builders whenever you accumulate a string as a result of many concatentations.

// Good
StringBuilder sb = new StringBuilder();
for (int i = 0; i < 100; ++i)
    sb.Append(i.ToString());
string result = sb.ToString();

// Bad
string result = "";
for (int i = 0; i < 100; ++i)
    result += i.ToString();

• Favor encapsulation over inheritance.
• Minimize the number of publically-accessible variables/methods.
• Favor immutable data structures whereever possible.
• Favor joins over multiple database queries where possible (note: LINQ is not very good at anything but inner joins).

References

• http://msdn.microsoft.com/en-us/library/ms229042.aspx