Table of Contents
The manual of style is the Box Social `coding guidelines`. These guidelines cover 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.
Most of the layout guidelines are Visual Studio defaults.
/*
* Box Social™
* http://boxsocial.net/
* Copyright © 2007, David Lachlan 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 3 as
* published by the Free Software Foundation.
*
* 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/>.
*/
Indented sections are indented by four spaces per indent, always. You should set your editor up to translate the tab key to indenting by four characters.
Indent block contents by a single indentation.
Do not indent braces.
Indent case contents. This includes the break keyword.
Indent case labels.
New lines in files are the "Windows" CR+LF combination.
The keywords, else, catch, and finally are to be placed on new lines by themselves.
The base keyword shall be on a new line (including the preceding colon).
Opening braces go on a new line.
There shall no space in between the function name, and the opening bracket of the parameter.
There shall no space in between empty parentheses.
There shall no space in between an enumerated variable, and the enumerated item accessor (opening square bracket).
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.
There shall be a space in between the opening, and closing brace and brace enclosed contents.
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...)
Always parenthesise complex boolean logic expressions. A complex expression is one that consists of more than one comparison operator.
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.
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:
Words ending in -ise not -ize.
Words ending in -our not -or.
Programme not program.
Singular of data is datum.
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.