Manual of Style

Introduction

General

The manual of style is the Box Social `coding standard`. This standard covers the production of C# code, HTML, English language files, and graphical elements.

This guide exists to keep the style of the project in sync and manageable such that anyone familiar with the style can understand the project sources.

Referenced standards

  • xHTML 1.1 strict [http://www.w3.org/TR/xhtml11/]
  • SVG 1.1 [http://www.w3.org/TR/SVG11/]
  • ISO/IEC 23270:2006 - Information technology - Programming languages - C#
  • ISO/IEC 16262:2002 - Information technology - ECMAScript language specification

C# Coding Standard

General

Most of the layout standards are Visual Studio defaults.

Standard C# File Header

All C# source files shall use the following header at the top of each file before any other content or whitespace.

Standard C# File Header


/*
 * Box Social™
 * [url]http://boxsocial.net/[/url]
 * Copyright © 2007, David Smith
 * 
 * $Id:$
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 of
 * the License, or (at your option) any later version.
 *
 * This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.
 */

Indentation

Indented sections shall be indented by four (4) spaces per indent, always.

You should set your editor up to translate the tab key to indenting by four characters.

Block contents shall be indented by a single indentation.

Example block indentation


public override string Name
{
    get
    {
        return "Networks";
    }
}

Braces shall not be indented.

Example wrong brace indentation


public override string Name
    {
        get
            {
                return "Networks";
            }
    }

Case contents shall be indented. This includes the break keyword.

Case labels shall be indented.

Example switch block indentation


switch (type)
{
    case "USER":
        DoThis();
        break;
    default:
        return;
}

New Lines

New lines in files shall be the "Windows" CR+LF combination.

The keywords, else, catch, and finally shall be placed on new lines by themselves.

Example correct if/else statement


if (true)
{
    DoThis();
}
else
{
    DoThat();
}

Example wrong if/else statement


if (true)
{
    DoThis();
} else {
    DoThat();
}

The base keyword shall be indented a single (1) indent on a new line (including the preceding colon).

Example constructor statement with base keyword


Forum(Core core, long forumId)
    : base(core)
{
    LoadItem(forumId);
}

Braces

Opening braces go on a new line.

Example brace usage


public override string Name
{
    get
    {
        return "Networks";
    }
}

Spacing

There shall no space in between the function name, and the opening bracket of the parameter.

Example function spacing


public new long Delete()
{
    Delete();
}

Example wrong function spacing


public new long Delete ()
{
    Delete();
}

There shall no space in between empty parentheses.

Example wrong function parenthesisation


public new long Delete( )
{
    Delete();
}

There shall be no space in between an enumerated variable, and the enumerated item accessor (opening square bracket).

Example of correct use of enumerated variable


long userId = users[0].Id;

Example of wrong use of enumerated variable


long userId = users [0].Id;

There shall be no space in between the opening, and closing bracket and parenthesised contents.

There shall be no space in between the opening, and closing square bracket and square bracketed contents.

Example of wrong use of enumerated variable


long userId = users[ 0 ].Id;

There shall be a space in between the opening, and closing brace and brace enclosed contents.

Example of correct use of braces for enumerated lists


List<long> = new List<long>() { 0, 1, 2 };

There shall be a space in between a control flow statement and parentheses, such as if, else if, for, where,
and catch.

There shall be a space after a comma.

There shall be no space before a comma.

There shall be a space before and after the interface colon on class definitions.

There shall be a space after the base colon on constructor method definitions.

There shall be a space after the semi colon in for statements.

There shall be no space before the semi colon in for statements.

There shall be a space before and after a binary operator (+, *, -, /, &&, ||, etc...)

Parenthesising Complex Expressions

Always parenthesise complex boolean logic expressions. A complex expression is one that consists of more than one comparison operator.

Naming

All members are to be named using camel case. To remove confusion, camel case shall either be referred to
as upper camel case (UpperCamelCase) or lower camel case (lowerCamelCase), example in part.

Public members of a class, structure, or enumeration are always written in upper camel case.

Private members (e.g. local variables) of a class, or structure are always written in lower camel case.

Undefined and non-standard abbreviations are to be avoided.

Internal members are treated as public members.

Protected members are treated as private members.

A member is a function, procedure, property, or variable.

Constants are to be named using underscore separated words written in upper case.

ECMAScript (JavaScript)

General

ECMAScript should be used where appropriate to add value.

ECMAScript shall not be used to replace functionality that prevents browsers without ECMAScript from performing all functions.

Each application shall be permitted a single ECMAScript file to be included on pages generated by the application.

Coding standards from Section 2, “C# Coding Standard” shall be used unless stated otherwise by Section 3, “ECMAScript (JavaScript)”

HTML Standard

General

All HTML either in template files, or code generated shall be xHTML 1.1 strict compliant.

HTML should be free of hacks to make it work in specific browsers.

English Language Standard

General

The default language used throughout Box Social is English. It is preferred to use a formal international dialect in the default distribution as opposed to any regional dialect. The exception is the inclusion of Australianisms where suited. Regionalisms are not to be abused, and an abundance will cause them to be removed in favour of a more universal style of expression.

There are a number of conventions that are to be followed to make this easier:

  1. Words ending in -ise not -ize.
  2. Words ending in -our not -or.
  3. Programme not program.
  4. Singular of data is datum.
  5. Plural of forum is fora.

Comments, class, and variable names are to always be spelt correctly. If a spelling mistake is found, refactoring is to take place to correct it.

Unless stating a measurement, numbers below 10 are to be written out in full. For example, "I have two tickets to the concert" (quantity), versus "I bought a 2 l bottle of milk" (measurement). A count of an item reported by the software is to always be reported in arabic numerals.

A list written in-line of a body of text is to always have a comma precede the 'or' or 'and' adjoining the last item of the list.

The definition of 'or' is to be taken as exclusive or. Where an inclusive or is intended 'and/or' is to be written.

Conventions in technologies developed by a United States majority may require these conventions to not be upheld, for instance referencing 'background-color' in CSS. These are considered proper names which are always referred to in their original sense.

All technical writing shall be written in the past tense, written in third person.

The referencing standard shall be the IEEE style.


Last Modified: July 13, 2014 with 37 page views.

This page is licensed under the following license: GNU Free Document License