F12 Coding Guidelines
All our coding conventions should be referenced here. If you disagree with any listed convention, contact Martha or add a note here. Feel free to add anything you think is missing.
All interfaces, classes, and all non-obvious methods (for example: certain getters, setters are obvious) should be documented. Fields should probably be documented too.
Please try to keep all documentation accurate.
Note that Visual Studio needs well-formed XML documentation. It will probably complain without it.
Look at Microsoft's xml documentation example.
/// A short, preferably one-line description of what this class does / is responsible for.
/// <remarks> Any long comments or extras can be written here. </remarks>
public class TheBestClassEver
Example field documentation:
/// <summary> A short description of the field and any non-evident requirements it needs to have. </summary>
private string MyName
Example method documentation:
Always write down what the method does inside <summary>, a description of each parameter inside <param>, and a description of the return value in <returns>, if possible.
/// Describe what this method does, how to use it, and, if not self-evident, why it exists.
/// List all preconditions.
/// List all postconditions, if necessary.
/// Try to avoid putting implementation details here.
/// <param name="babyNames">Describe this parameter and possibly what it expects. For example, babyNames needs a non-empty, non-null list of Strings. </param>
public void NameBaby(String babyNames )
One-line comments are fine too:
/// <summary> This method returns the player's current health. </summary>
/// <returns> Int32 number between 0 and 100 </returns>
public void GetHealth()
Comments are mostly left up to the coder's discretion, with one exception: use comments to explain any non-obvious decisions.
The code itself should be clear enough to avoid lots and lots of non-documentation comments. But when in doubt, it's better to have too many comments than too few.
Use CamelCase for naming and VisualStudio's defaults for now.
Always capitalize the first letter of class names, interface names, and sadly enough method names. Otherwise, leave the first letter of the name lowercase.
Interface names always start with the capital letter 'I'.
Always use intention-revealing names.
Naming Convention Links: