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

Last edited May 22, 2009 at 8:41 PM by SergeySolyanik, version 23

Comments

No comments yet.