Stephen's Coding Standards

Commented Code

No commented code, unless there is a comment clearly explaining under what circumstances the code should be uncommented. The <html><acronym title=“You Ain't Gunna Need It”>YAGNI</acronym></html> principle should be kept in mind. If there are no circumstances in which the code should be uncommented, it should be deleted.

Justification: Commented code adds no value to the source. It does not clarify or explain functionality. It is old rubbish that should be removed. Source control is for looking at old code.

Comments

Comments should be

complete sentences,
on their own line, at the current indent
grammatically correct, spelt correctly and have the correct punctuation (including a capital letter at the start and a full stop at the end).

Names

Developer names should not appear in code.

Justification: The code belongs to the company not the individual developers that wrote it. Names in code encourages an attitude of certain developers 'owning' certain parts of the code or particular parts of functionality of the system. It also discourages other developers from changing the code due to a fear of standing on someone's toes. At TallGuyProgramming Inc, all developers are free to change any part of the code and developer specialisation is strongly discouraged.

Comma Separated Lists

Where a comma separated list is spilt over multiple lines, the commas should be prepended to the item. The first item should be indented, then have two spaces, then the item. Subsequent items should be indented, have a comma, have a space and then the item.

  →  ••Item one
  →  ,•Item two
  →  ,•Item three

Tabs Versus Spaces

Use tabs to indent, spaces to align. Tabs should only appear at the beginning of a line. No arguments, no debates, this is how things are done at TallGuyProgramming Inc.

SELECT 
  →  ··Name·········AS·CustomerName
  →  ,·CreatedDate··AS·OrginalCreatedDate
FROM
  →  Customers

Date Format

In all internal documents, code comments etc. dates will be written in the ISO 8601 format, i.e.:

yyyy-MM-dd

For example, 2001-01-01, 1956-12-31.

No other date formats are acceptable. The year shall not be abbreviated to two digits. The separator shall not be a slash or a comma or anything else. And don't even think about putting the year, month and day in a different order.

Note: This does not mean that software will use this format to display dates to the user. Dates displayed to the user should follow the system's regional settings.

When a date is used in a file name, directory name or source control tag or branch, the following variant of the ISO 8601 format will be used (and almost always prepended):

yyyyMMdd

For example, 20010101, 19561231.

Line Length

No line of code shall exceed 130 characters in length. Tabs count as four characters in this context. Use the Col value in the lower right of Visual Studio.

To get a visual margin guide in Visual Studio 2010, ensure the Productivity Power Tools extension is installed, right click the 130th column and select Guidelines → Add Guidelines from the context menu.

Blank Lines

Code shall not contain more than one blank line in a row. There's just no need.

Unnecessary Parentheses

Code shall not contain unnecessary parentheses. Developers are expected to be able to use C# operator precedence and SQL operator precedence to construct expressions that evaluate in the correct order without unnecessary parentheses.

Pointless Boolean Expressions

The following boolean expressions are pointless and are not allowed:

booleanExpression == true  // Use booleanExpression
booleanExpression != true  // Use !booleanExpression
booleanExpression == false // Use !booleanExpression
booleanExpression != false // Use booleanExpression
 
if (booleanExpression)
    return true;
return false;
// Use return booleanExpression;
 
if (booleanExpression)
    return false;
return true;
// Use return !booleanExpression;

Developers are expected to know and understand how boolean expressions work, how to express them in the simplist form possible, and understand and use the ! operator.

String Comparisons

The standard comparison operators (==, !=, <, >, <=, >=) shall not be used for string comparisons. The String.Equals() and String.Compare() methods should be used instead.

When using the String.Equals(), String.Compare() or String.IndexOf() method, the StringComparison option shall always be specified.

The String.ToUpper(), String.ToUpperInvariant(), String.ToLower() or String.ToLowerInvariant() method shall never be used to do a case insensitive comparison. Use the IgnoreCase version of the StringComparison option.

Which StringComparison should be used?

To do a comparison like a machine, use StringComparison.Ordinal or StringComparison.OrdinalIgnoreCase.
To do a comparison like a human, use StringComparison.CurrentCulture or StringComparison.CurrentCultureIgnoreCase.
It is extremely unlikely that StringComparison.InvariantCulture or StringComparison.InvariantCultureIgnoreCase would ever need to be used.

Machine or Human? WTF?

The German alphabet has the letter 'ß', which basically means 'double S'. So a German-speaking human will see 'Boss' and 'Boß' as meaning exactly the same thing. A machine won't:

String.Compare("Boss", "Boß", StringComparison.Ordinal);        // = false
String.Compare("Boss", "Boß", StringComparison.CurrentCulture); // = true

(In this example it does not seem to matter what the current culture is set to, but there will be other examples where it does.)

CurrentCulture vs CurrentUICulture

CultureInfo.CurrentCulture should be used for number, date and string formatting. It is probably the one you want to use.

CultureInfo.CurrentUICulture should be used for determining the default user interface language.

(date, currency, double).ToString = CultureInfo.CurrentCulture
 
resource.fr-CA.resx file = CultureInfo.CurrentUICulture

Switch Case

If a Switch Case is intended to cover every case, it must include a default clause that throws an exception.
If a Switch Case is intended to only cover some cases, it must include a comment to that effect.

Exceptions

Exceptions shall not be 'swallowed' without a damn good, well documented reason:

// Career limiting code:
catch (Exception ex)
{
}

Thou shall not throw a new exception in a catch clause without a damn good, well documented reason and the original exception shall be passed into the new exception as an inner exception.

// Career limiting code:
catch (Exception ex)
{
    throw new Exception("Something went wrong.");
}

Id

The correct capitalisation of 'id' is 'Id', not 'ID' as it is an abbreviation, not an initialisation.

SQL

Capitalisation

Keywords are upper cased (SELECT INSERT INTO UPDATE DELETE EXEC UNION INNER JOIN ON AS ORDER BY WITH DECLARE etc.)

Functions are upper cased (CAST CONVERT GETDATE etc.)

Built in types are lower cased (varchar int money uniqueidentifier etc.)

Variables, table aliases and column aliases are title cased.

The names of user database objects are title cased (tables, columns, views, stored procedures etc.)

Web.config

The <connectionStrings> section shall be directly after the <configSections> section if it exists or the first element in the <configuration> if it does not.

code, standard, rant

Stephen's Wiki

Table of Contents