Coding Conventions

The coding conventions are not written in stone (and some older code won't fit the coding conventions as two years in a more structured development environment have changed my thoughts on some things) but there are some guidelines that will keep code consistent.

All new code should follow the following conventions as closely as possible, unless there is a good reason not to. Old code should be updated when it is modified but doesn't need to be updated to meet the conventions just for the sake of updating it.

File Headers

All of the WarFoundry code is currently licensed under the AGPL v3. This means that there must be a copyright line and a license line at the top of each file, plus all projects must include the COPYING.AGPL and COPYING.GPL files. Although GNU recommend putting a large chunk of comments at the top of the page this is generally excessive and can be replaced with the following:

 This file (${FileName}) is a part of the ${ProjectName} project and is copyright ${Year} ${CopyrightHolder}

 The file and the library/program it is in are licensed under the GNU AGPL license, either version 3 of the License or (at your option) any later version. Please see COPYING.AGPL for more information and the full license.

If this is used in MonoDevelop then all of the variables will be replaced with valid values (as long as you've filled out the "Author Information"). Other applications may have similar templating for auto-inserted headers. The final alternative is to add the values manually.

Capitalisation

The standard .Net capitalisation conventions should be followed - classes, methods, properties and namespaces are in "Pascal Case", while class fields and parameters are in "camel Case".

Brackets

There are many different ways of handling brackets, and people don't always agree, but this is the convention we're aiming for at the moment. The following uses "brackets" and "braces" interchangeable. "Curly brackets" are block statement wrappers ("{" and "}") while "rounded brackets" are standard parenthesis ("(" and ")").

Brackets or no brackets

The curly type

Wherever curly braces can go, they should go. That means single line "if", "else" or other block statements should still have braces for clarity.

Bad:

if (someString == null)
    someString = GetDefaultValue();

Good:

if (someString == null)
{
    someString = GetDefaultValue();
}

Adding brackets doesn't take long, it improves clarity, it removes the possibility of code accidentally being outside of a code block when it should be in it, and IDEs can often put braces in for you anyway.

The round type

Round brackets - "()" - should be added wherever they clarify a statement. Sometimes they can help, sometimes they hinder. It's more of a personal judgement than curly brackets, but quite often less is more.

Curly brackets and new lines

Curly brackets should always be on a new line. Older code may not follow this convention, but it makes more sense as it more definitively marks out the start and end of a block.

Indentation

Indentation should be done in tabs so that each person can select their own value. The content of each level of a block statement should be written one level more indented than the curly braces that define it. The curly braces should be at the same level as the outer block statement.

Bad:

if (someString == null)
{
someString = GetDefaultValue();
}

Bad:

if (someString == null)
    {
    someString = GetDefaultValue();
    }

Good:

if (someString == null)
{
    someString = GetDefaultValue();
}

Indentation and long lines

If a line is so long that it is best wrapped on to two or more lines then the additional lines should be indented by one level.

In general breaking a single instruction across multiple lines should be avoided. If lines are getting too long to fit on a page then it normally means too much is being done in one go. Try breaking the line in to separate lines by extracting values in to variables and passing the variables instead.

Last modified 8 years ago Last modified on 12/07/10 21:53:02