Coding Standards

Introduction

Some guidelines, such those about as comments and indentation, are based purely on convention, rather than on clear technical merit. However, conventions are important for readability, thus most conventions are musts.

A lot of our code was written before these guidelines existed. You should fix violations as you encounter them in the course of your normal coding. You must not fix violations en masse without warning other developers and coordinating with them, so as not to make the merging of branches more difficult than it already is.

We have added an editor.config file that will help enforce some of these standards. Changes should not be made to this file without discussion or agreement from team members.

Casing

Token	Casing Style	Example
Types	Pascal	public class SomeClass
Methods	Pascal	private int SomeFunction()
Local Variables	Camel	var myVariable
Method Arguments	Camel	protected void SomeSubroutine(Object myParameter)
Private Memeber Variables	Camel, underscore prefix	private int _myCounter
Private Constants	All caps, underscore-seperated, underscore-prefix	private const String _EMPLOYEE_FIRST_NAME
Non-private Constants	All caps, underscore-seperated, no prefix	private const String PATH_TO_IMPORTANT_FILE

Constructors

Do not perform any work in a constructor that could throw an exception. Do not perform work in a constructor that hits an external dependency, including but not limited to:

• Filesystem access
• Network access
• Threading

Documentation

Never use /* and */ to comment, use //
//Good
/* Bad */

Indent comments at the same level of indentation of the code being documented, and use XML-style comments where applicable.

Avoid comments that explain the obvious. Code should be self-explanatory. Good code with readable variable and method names should not require comments.

Document only operational assumptions, algorithm insights and the like.

Do not check in commented-out code.

Code level comments should be in full, grammatically correct sentences. Punctuate, capitalize, etc. Avoid jargon and shorthand.

Do not check in empty XML comments.

Use the //TODO: and //HACK: comments to force IDE tasks:

Work in progress