Skip to content

Latest commit

 

History

History
293 lines (251 loc) · 13 KB

CONTRIBUTING.md

File metadata and controls

293 lines (251 loc) · 13 KB
Raw

This document is stolen from jittuu's Coding Guidelines.

Coding Guidelines

Let's face it. No matter what coding guidelines we choose, we're not going to make everyone happy. While we would like to embrace everyone's individual style, working together on the same codebase would be utter chaos if we don't enforce some consistency. When it comes to coding guidelines, consistency can be even more important than being "right."

Definitions

  • Camel case is a casing convention where the first letter is lower-case, words are not separated by any character but have their first letter capitalized. Example: thisIsCamelCased.
  • Pascal case is a casing convention where the first letter of each word is capitalized, and no separating character is included between words. Example: ThisIsPascalCased.

C# coding conventions

Tabs & Indenting

Tab characters \0x09 should not be used in code. All indentation should be done with 4 space characters.

Bracing

Open braces should always be at the beginning of the line after the statement that begins the block. Contents of the brace should be indented by 4 spaces. For example:

if (someExpression)
{
    DoSomething();
}
else
{
    DoSomethingElse();
}

Braces should never be considered optional. Even for single statement blocks, you should always use braces. This increases code readability and maintainability.

for (int i=0; i < 100; i++) { DoSomething(i); }

Single line statements

Single line statements can have braces that begin and end on the same line.

public class Foo
{
    int bar;

    public int Bar
    {
      get { return bar; }
      set { bar = value; }
    }
}

Commenting

Only comment the "Why" and not the "What". Jeff posted a good blog post about it.

Naming

  • ❌ DO NOT use Hungarian notation
  • ✅ DO use a prefix with an underscore _ and camelCased for private fields.
  • ✅ DO use camelCasing for member variables
  • ✅ DO use camelCasing for parameters
  • ✅ DO use camelCasing for local variables
  • ✅ DO use PascalCasing for function, property, event, and class names
  • ✅ DO prefix interfaces names with “I”
  • ❌ DO NOT prefix enums, classes, or delegates with any letter

Region

  • ✅ DO use region where useful.

StyleCop

We use StyleCop with the following rules to ensure that we have the same coding style in the organization.

Layout Rules

SA1500-SA1518, except SA1513

  • SA1500: Curly brackets for multiline statements must not share line
  • SA1501: Statement must not be on single line
  • SA1502: Element must not be on single line
  • SA1503: Curly brackets must not be omitted
  • SA1504: All accessors must be multiline or single line
  • SA1505: Opening curly brackets must not be followed by blank line
  • SA1506: Element documentation headers must not be followed by blankline
  • SA1507: Code must not contain multiple blank lines in a row
  • SA1508: Closing curly brackets must not be preceded by blank line
  • SA1509: Opening curly brackets must not be precededed by blank line
  • SA1510: Chained statement blocks must not be preceded by blank line
  • SA1511: While do footer must not be preceded by blank line
  • SA1512: Single line comments must not be followed by blank line
  • SA1514: Element documentation header must be preceded by blank line
  • SA1515: Single line comment must be preceded by blank line
  • SA1516: Elements must be separated by blank line
  • SA1517: Code must not contain blank lines at start of file
  • SA1518: Code must not contain blank lines at end of file

Maintainability Rules

  • SA1403: File may only contain a single namespace
  • SA1404: Code analysis suppression must have justification

Naming Rules

SA1300-SA1311, except SA1306 and SA1309

  • SA1300: Element must begin with upper case letter
  • SA1301: Element must begin with lower case letter
  • SA1302: Interface names must begin with I
  • SA1303: Const field names must begin with upper case letter
  • SA1304: Non private readonly fields must begin with upper case letter
  • SA1305: Field names must not use hungarian notation
  • SA1307: Accessible fields must begin with upper case letter
  • SA1308: Variable names must not be prefixed
  • SA1310: Field names must not contain underscore
  • SA1311: Static readonly fields must begin with upper case letter

Readability Rules

SA1106-SA1108

  • SA1106: Code must not contain empty statements
  • SA1107: Code must not contain multiple statements on one line
  • SA1108: Block statements must not contain embedded comments

Spacing Rules

SA1000-1027

  • SA1000: Keywords must be spaced correctly
  • SA1001: Commas must be spaced correctly
  • SA1002: Semicolons must be spaced correctly
  • SA1003: Symbols must be spaced correctly
  • SA1004: Documentation lines must begin with single space
  • SA1005: Single line comments must begin with singe space
  • SA1006: Preprocessor keywords must not be preceded by space
  • SA1007: Operator keyword must be followed by space
  • SA1008: Opening parenthesis must be spaced correctly
  • SA1009: Closing parenthesis must be spaced correctly
  • SA1010: Opening square brackets must be spaced correctly
  • SA1011: Closing square brackets must be spaced correctly
  • SA1012: Opening curly brackets must be spaced correctly
  • SA1013: Closing curly brackets must be spaced correctly
  • SA1014: Opening generic brackets must be spaced correctly
  • SA1015: Closing generic brackets must be spaced correctly
  • SA1016: Opening attribute brackets must be spaced correctly
  • SA1017: Closing attribute brackets must be spaced correctly
  • SA1018: Nullable type symbols must not be preceded by space
  • SA1019: Member access symbols must be spaced correctly
  • SA1020: Increment decrement symbols must be spaced correctly
  • SA1021: Negative signs must be spaced correctly
  • SA1022: Positive signs must be spaced correctly
  • SA1023: Dereference and access of symbols must be spaced correctly
  • SA1024: Colons must be spaced correctly
  • SA1025: Code must not contain multiple whitespace in a row
  • SA1026: Code must not contain space after new keyword in implicitly typed array allocation
  • SA1027: Tabs must not be used

FxCop

We will use FxCop as code analysis tool to enforce coding best practices. The ruleset includes ALL rules as Error - EXCEPT the following rules:

  • CA1002: Do not expose generic lists
  • CA1006: Do not nest generic types in member signatures
  • CA1014: Mark assemblies with CLSCompliantAttribute
  • CA1017: Mark assemblies with ComVisibleAttribute
  • CA1020: Avoid namespaces with few types
  • CA1024: Use properties where appropriate
  • CA1026: Default parameters should not be used
  • CA1062: Validate arguments of public methods
  • CA1303: Do not pass literals as localized parameters
  • CA1305: Specify IFormatProvider
  • CA1307: Specify StringComparison
  • CA1309: Use ordinal StringComparison
  • CA1726: Use preferred terms
  • CA1819: Properties should not return arrays
  • CA1820: Test for empty strings using string length
  • CA2204: Literals should be spelled correctly
  • CA2210: Assemblies should have valid strong names

Ruleset

<?xml version="1.0" encoding="utf-8"?>
<RuleSet Name="FxCop rules for software development" Description="This rule set contains the rules for software development." ToolsVersion="12.0">
  <IncludeAll Action="Error" />
  <Rules AnalyzerId="Microsoft.Analyzers.ManagedCodeAnalysis" RuleNamespace="Microsoft.Rules.Managed">
    <Rule Id="CA1002" Action="None" />
    <Rule Id="CA1006" Action="None" />
    <Rule Id="CA1014" Action="None" />
    <Rule Id="CA1017" Action="None" />
    <Rule Id="CA1020" Action="None" />
    <Rule Id="CA1024" Action="None" />
    <Rule Id="CA1026" Action="None" />
    <Rule Id="CA1062" Action="None" />
    <Rule Id="CA1303" Action="None" />
    <Rule Id="CA1305" Action="None" />
    <Rule Id="CA1307" Action="None" />
    <Rule Id="CA1309" Action="None" />
    <Rule Id="CA1726" Action="None" />
    <Rule Id="CA1819" Action="None" />
    <Rule Id="CA1820" Action="None" />
    <Rule Id="CA2204" Action="None" />
    <Rule Id="CA2210" Action="None" />
  </Rules>
</RuleSet>