Binary Spectrum: C# Coding Standards

Industries

Quick Contact Us

Our Technology Partners

You are Here:

Home

knowledge Bank

Knowledge Bank -C# Coding Standards

Table of Contents
	Introduction
	Naming Conventions
	Coding Style
	Language Usage
	Object Mode Design
	References

1. Introduction

This document describes rules and recommendations for developing applications and class libraries using the C# Language. The goal is to define guidelines to enforce consistent style and formatting and help developers avoid common pitfalls and mistakes. Specifically, this document covers Naming Conventions, Coding Style, Language Usage, and Object Model Design.

This document only applies to the C# Language and the .NET Framework Common Type System(CTS) it implements. Although the C# language is implemented alongside the .NET Framework, this document does not address usage of .NET Framework class libraries. However, common patterns and problems related to C#'s usage of the .NET Framework are addressed in a limited fashion. Even though standards for curly-braces ({ or }) and white space(tabs vs. spaces) are always controversial, these topics are addressed here to ensure greater consistency and maintainability of source code.

1.2 Document Conventions

Much like the ensuing coding standards, this document requires standards in order to ensure clarity when stating the rules and guidelines. Certain conventions are used throughout this document to add emphasis. Below are some of the common conventions used throughout this document.

Coloring & Emphasis:

Blue Text colored blue indicates a C# keyword or .NET type.

Bold Text with additional emphasis to make it stand-out.

Keywords:

Always - Emphasizes this rule must be enforced.

Never - Emphasizes this action must not happen.

Do Not - Emphasizes this action must not happen.

Avoid - Emphasizes that the action should be prevented, but some exceptions may exist.

Try - Emphasizes that the rule should be attempted whenever possible and appropriate.

Example - Precedes text used to illustrate a rule or recommendation.

Reason - Explains the thoughts and purpose behind a rule or recommendation.

1.3 Terminology & Definitions

The following terminology is referenced throughout this document:

Access Modifier

C# keywords public, protected, internal and private declare the allowed code accessibility of types and their members. Although default access modifiers vary, classes and most other members use the default of private. Notable exceptions are interfaces and enums which both default to public.

Camel Case

A word with the first letter lowercase, and the first letter of each subsequent word-part capitalized.
Example: customerName

Common Type System

The .NET Framework common type system (CTS) defines how types are declared, used, and managed. All native C# types are based upon the CTS to ensure support for cross-language integration.

Identifier

A developer defined token used to uniquely name a declared object or object instance.

Example: public class MyClassNameIdentifier { … }

Magic Number

Any numeric literal used within an expression (or to initialize a variable) that does not have an obvious or well-known meaning. This usually excludes the integers 0 or 1 and any other numeric equivalent precision that evaluates as zero.

Pascal Case

A word with the first letter capitalized, and the first letter of each subsequent word-part capitalized.
Example: CustomerName

Premature Generalization

As it applies to object model design; this is the act of creating abstractions within an object model not based upon concrete requirements or a known future need for the abstraction. In simplest terms: “Abstraction for the sake of Abstraction.”

1.4 Quick Summary

This section contains tables describing a high-level summary of the major standards covered in this document. These tables are not comprehensive, but give a quick glance at commonly referenced elements.

1.4.1 Naming Conventions

“c” = camelCase
“P” = PascalCase
“_” = Prefix with _Underscore
“x” = Not Applicable

1.4.2 Coding Style

1.4.3 Language Usage

2. Naming Conventions

Consistency is the key to maintainable code. This statement is most true for naming your projects, source files, and identifiers including Fields, Variables, Properties, Methods, Parameters, Classes, Interfaces, and Namespaces.

2.1 General Guidelines

1. Always use Camel Case or Pascal Case names.

2. Avoid ALL CAPS and all lowercase names. Single lowercase words or letters are acceptable.

3. Do not create namespaces, classes, methods, properties, fields, or parameters that vary only by capitalization.

4. Do not use names that begin with a numeric character.

5. Always choose meaningful and specific names.

6. Always err on the side of verbosity not terseness.

7. Variables and Properties should describe an entity not the type or size.

8. Do not use Hungarian Notation!

Example: strName or iCount

9. Avoid using abbreviations unless the full name is excessive.

10. Avoid abbreviations longer than 5 characters.

11. Any Abbreviations must be widely known and accepted.

12. Use uppercase for two-letter abbreviations, and Pascal Case for longer abbreviations.

13. Do not use C# reserved words as names.

14. Avoid naming conflicts with existing .NET Framework namespaces, or types.

15. Avoid adding redundant or meaningless prefixes and suffixes to identifiers

Example:
   // Bad!
    Public enum ColorEnum { … }
    Public class Cvehicle { … }
    Public struct RectangleStruct { … }

Example: Customer.Name NOT Customer.CustomerName

17. Try to prefix Boolean variables and properties with “Can”, “Is” of “Has”.

18. Append computational qualifiers to variable names like Average, Count, Sum, Min and Max where appropriate.

19. When defining a root namespace, use a Product, Company or Developer Name as the root.

Example: VandanDesai.StringUtilities

2.2 Name Usage and Syntax

3. Coding Style

Coding style causes the most inconsistency and controversy between developers. Each developer has a preference, and rarely are two the same. However, consistent layout, format, and organization are key to creating maintainable code. The following sections describe the preferred way to implement C# source code in order to create readable, clear, and consistent code that is easy to understand and maintain.

1.Never declare more than 1 namespace per file.

2. Avoid putting multiple classes in a single file.

3. Always place curly braces ({ and }) on a new line.

4. Always use curly braces ({ and }) in conditional statements.

5. Always use a Tab & Indention size of 4.

6. Declare each variable independently – not in the same statement.

7. Place namespace “using” statements together at the top of file. Group .NET namespaces above custom namespaces.

8. Group internal class implementation by type in the following order:

a. Member Variables

b. Constructors and Finalizers

c. Nested Enums, Structs and Classes.

d. Properties

e. Methods

9. Sequence declarations within type groups based upon access modifiers and visibility:

a. Public

b. Protected

c.Internal

d.Private

10. Segregate interface implementation by using #region statements.

11. Append folder-name to namespace for source files within sub-folders.

12. Recursively indent all code blocks contained within braces.

13. Use white space (CR/LF, Tabs, etc) liberally to separate and organize code.

14. Avoid declaring multiple attribute declarations within a single line. Instead stack each attribute as a separate declaration.

Example:

// Bad !
[Attribute1, Attribute2, Attribute3]
public class MyClass
{…}

// Good!
[Attribute1]
[Attribute2]
[Attribute3]
public class MyClass
{…}

15. Place Assembly scope attribute declarations on a separate line.

16. Place Type scope attribute declarations on a separate line.

17. Place Method scope attribute declarations on a separate line.

18. Place Member scope attribute declarations on a separate line.

19. Place Parameter attribute declarations inline with the parameter.

20. If in doubt, always err on the side of clarity and consistency.

3.2 Coding Standards

21. All comments should be written in U.S. English

22. Use // or /// but never /* … */

23. Do not use “flowerbox” comment boxes.

Example

// **********************************************
// Comment Block
// **********************************************

24. Use inline comments to explain assumptions, known issues, and algorithms insights.

25. Do not use inline-comments to explain obvious code. Well written code is self documenting.

26. Only insert inline-comments for Bad Code to say “fix this code” – otherwise, rewrite it!

27. Include Task-List keyword flags to enable comment-filtering.

Example:

// TODO: Place database code here.

// UNDONE: Removed P\Invoke Call due to error.

// HACK: Temporary fix until able to refactor.

28. Always apply C# comment-blocks (///) to public, protected and internal declarations.

29. Only use C# comment-blocks for documenting the API.

30. Always include <summary> comments. Include <params>, <return> and <exception> comment sections where applicable.

31. Include <see cref = “” /> abd <seeAlso cref=””/> where possible.

32. Always add CDATA tags to comments containing code and other embedded markup in order to avoid encoding issues.

Example:

/// <example>
/// Add the following key to the “appSettings” section of your config:
/// <codes><![CDATA[
/// <configuration>
/// <appSettings>
/// <add key = ”mySetting” value = “myValue”/>
/// </appSettings>
/// </configuration>
/// ]]></code>
/// <example>

4. Language Usage

4.1 General

1. Do not omit access modifiers. Explicitly declare all identifiers with the appropriate access modifier instead of allowing the default.

Example:

// Bad!
Void WriteEvent(string message)
{…}

// Good!
private Void WriteEvent(string message)
{…}

2. Do not use the default (“1.0.*”) versioning scheme. Increment the AssemblyVersionAttribute value manually.

3. Set the ComVisibleAttribute to false for all assemblies. Afterwards, selectively enable the ComVisibleAttribute for individual classes as needed.
Example:

[assembly: ComVisible(false)]
[ComVisible(true)]
public MyClass()
{…}

4. Consider factoring classes with unsafe code blocks into a separate assembly.

5. Avoid mutual references between assemblies.

.2 Variables & Types

6. Try to initialize variables where you declare them.

7. Use the simplest data type, list or object required. For example, use int over Long unless you know you need to store 64 bit values.

8. Always use the built-in C# data types aliases, not the .NET common type system (CTS).

Example:

short NOT System.Int16
int NOT System.Int32
long NOT System.Int64
string NOT System.String

9. Only declare member variables as private. Use properties to provide access to them with public, protected or internal access modifiers.

10. Avoid specifying a type for an enum – use default of int unless you have an explicit need for long.

11. avoid using inline numeric literals (magic numbers). Instead, use a Constant or Enum.

12. Avoid declaring inline string literals. Instead use Constants, Resources, Registry or other data sources.

13. Only declare constants for simple types.

14. Declare readonly or static readonly variables instead of constants for complex types.

15. Avoid direct casts. Instead, use the “as” operator and check for null.

Example:

object dataObject = LoadData();
DataSet ds = dataObject as DataSet;

If(ds != null)
{…}

16. Always prefer C# Generic collection types over standard or strong – typed collections.

17. Always explicitly initialize arrays of reference types using a for loop.

18. Avoid boxing and unboxing value types.

Example:

int count = 1;
object refCount = count; // Implicityly boxed.
int newCount = (int)refCount; // Explicitly unboxed.

9. Floating point values should include at least one digit before the decimal place and one after.

Example: totalPercent = 0.05;

20. Try to use the “@” prefix for string literals instead of escaped strings.

21. Prefer String.Format() or StringBuilder over string concatenation.

22. Never concatenate string inside a loop.

23. Do not compare strings to String.Empty or " " to check for empty strings. Instead, compare by using String.Length == 0.

24. Avoid hidden string allocations within a loop. Use String.Compare() instead.

Example: (ToLower() creates a temp string)

// Bad!
int id = -1;
string name = “vandan desai”;

for(int i=0; i < customerList.Count; i++)
{
if(customerList[I].Name.ToLower() == name)
{
id = customerList[I].ID;
}
}

// Good!
int id = -1;
string name = “vandan desai”;

for(int i=0; I < customerList.Count; i++)
{
// The “ignoreCase = true” argument performs a
// case-insensitive compare without new allocation.
if(String.Compare(customerList[i].Name, name, true) == 0)
{
id = customerList[I].ID;
}
}

25. Avoid invoking methods within a conditional expression.

26. Avoid creating recursive methods. Use loops or nested loops instead.

27. Avoid using foreach to iterate over immutable value-type collections. E.g. String arrays.

28. do not modify enumerated items within a foreach statement.

29. Use the ternary conditional operator only for trival conditions. Avoid complex or compound ternary operations.

Example:

int result = isValid ? 9 : 4;

30. Avoid evaluating Boolean conditions against true or false.

Example:

// Bad!
if(isValid == true)
{…}

// Good!
if(isValid)
{…}

31. Avoid assignment within conditional statements.

Example
if((i = 2) == 2)
{…}

32. Avoid compound conditional expressions – use Boolean variables to split parts into multiple manageable expressions.

Example

// Bad!
if(((value > _highScore) && (value != _highScore)) && (value < _maxScore))
{…}

// Good!
isHighScore = (value >= _highScore);
isTideHigh = (value == _highScore);
isValid = (value < _maxValue);

if((isHighScore && ! isTideHigh) && isValid)
{…}

33. Avoid explicit Boolean tests in conditionals.

Example:

// Bad!
if(IsValid == true)
{…};

// Good!
if(IsValid)
{…}

34. Only use switch/case statements for simple operations with parallel conditional logic.

35. Prefer nested if/else over switch/case for short conditional sequences and complex conditions.

36. Prefer polymorphism over switch/case to encapsulate and delegate complex operations.

4.4 Exception Handling

37. Do not use try/catch blocks for flow control.

38. Only catch exceptions that you can handle.

39. Never declare an empty catch block.

40. Avoid nesting a try/catch within a catch block.

41. Use exception filters where possible.

42. Order exception filters from most to least derived exception type.

43. Avoid re-throwing an exception. Allow it to bubble-up instead.

44. If re-throwing an exception, omit the exception argument from the throw statement so the original call stack is preserved.

Example:

// Bad!
catch(Exception ex)
{
Log(ex)
throw ex;
}

// Good!
catch(Exception ex)
{
Log(ex)
throw;
}

45. Only use the finally block to release resources from a try statement.

46. Always use validation to avoid exceptions.

Example:

// Bad!
try
{
conn.Close();
}
catch(Exception ex)
{
// handle exception if already closed!
}

// Good!
if(conn.State != ConnectionState.Closed)
{
conn.Close();
}

47. Avoid defining custom exception classes. Use existing exception classes instead.

48. When a custom exception is required;

a. Always derive from Exception not ApplicationException

b. Always override the ToString() method and String implicit operator to provide serialization.

c. Always implement the Exception Constructor Pattern:

public MyCustomException();

public MyCustomException(string message);

public MyCustomException(string message, Exception innerException);

49. When throwing a new Exception, always pass the innerException in order to maintain the exception tree and inner call stack.

4.5 Events, Delegates & Threading

50. Always check Event & Delegate instances for null before invoking.

51. Use the default EventHandler and EventArgs for most simple events.

52. Always derive a custom EventArgs class to provide additional data.

53. Use the existing CancelEventArgs class to allow the event subscriber to control events.

54. Always use the “lock” keyword instead of the Monitor type.

55. Only lock on private or private static object.

Example: lock(myVariable);

56. Avoid locking on a Type.

Example: lock(typeof(MyClass));

57. Avoid locking on the current object instance.

Example: lock(this);

4.6 Object Composition

58. Always declare types explicitly within a namespace. Do not use the default “{global}” namespace.

59. Avoid declaring methods with more than 7 parameters. Refactor or consider passing a struct or class instead.

60. Do not use the “new” keyword to hide members of a derived type.

61. Only use the “base” keyword when invoking a base class constructor or base implementation within an override.

62. Do not use the protected access modifier in sealed classes.

63. Consider using method overloading instead of the params attribute.

64. Always validate an enumeration variable or parameter value before consuming it. They may contain any value that the underlying Enum type (default int) supports.

Example:

public void Test(BookCategory cat)
{
if(Enum.IsDefined(typeof(BookCategory), cat))
{…}
}

65. Consider overriding Equals() on a struct.

66. Always override the Equality Operator (==) when overriding the Equals() method.

67. Always override the String Implicit Operator when overriding the ToString() method.

68. Always call Close() or Dispose() on classes that offer it.

69. Wrap instantiation of IDisposable objects with a “using” statement to ensure that Dispose() is automatically called.

Example:

using(SqlConnection cn = new SqlConnection(_connectionString))
{…}

70. Always implement the IDisposable interface & pattern on classes referencing external resources.

Example

public void Dispose()
{
Dispose(true);
GC.SuppressFinalize(this);
}

protected virtual void Dispose(bool disposing)
{
if(disposing)
{
// Free other state (managed objects).
}
// Free your own state (unmanaged objects).
// Set large fields to null.
}

// C# Finalizer. (optional)
~Base()
{
// Simply call Dispose(false)
Dispose(false);
}

71. Avoid implementing a Finalizer.
Never define a Finalize() method as a Finalizer. Instead use the C# destructor syntax.

Example:

// Bad!
void Finalize()
{…}

// Good!
~MyClass()
{…}

5. Object Model Design

1. Always prefer delegation over inheritance.

2. Avoid “Premature Generalization”. Create abstraction only when the intent is understood.

3. Do the simplest thing that works, then refactor as time permits.

4. Always make object-behavior transparent to API consumers.

5. Always separate presentation layer from the business logic.

6. Always prefer interfaces over abstract classes.

7. Try to append the design-pattern name to class names where appropriate.

8. Make members virtual if they are designed and tested for extensibility.

9. Consider using the “sealed” keyword to break the inheritance chain.

10. Refactor! Refactor! Refactor!

6. References

MSDN: .NET Framework Developer’s Guide: Common Type System”, Microsoft Corporation, 2004.

Content on this page requires a newer version of Adobe Flash Player.