C# Coding Standards

C# Coding Standards

C# Coding Standards
Your Company Name Here
Abstract This document contains coding conventions and style guidelines that will ensure that C# code will be of consistent and superior quality. It includes general coding guidelines as well as

Nội dung Text: C# Coding Standards

C# Coding Standards
Your Company Name Here
Abstract
This document contains coding conventions and style guidelines that will ensure that C# code will be
of consistent and superior quality. It includes general coding guidelines as well as discussions on
naming, formatting, and language usage patterns.

1. Introduction
1.1 Purpose
The purpose of this document is to provide coding style standards for the development of source code written in C#.
Adhering to a coding style standard is an industry proven best-practice for making team development more efficient and
application maintenance more cost-effective. While not comprehensive, these guidelines represent the minimum level of
standardization expected in the source code of projects written in C#.
1.2 Scope
This document provides guidance on the formatting, commenting, naming, and programming style of C# source code and
is applicable to component libraries. web services, web sites, and rich client applications.
1.3 Document Conventions
Example code is shown using the Code font and shows syntax as it would be color coded in Visual Studio’s code editor.
1.4 Feedback
Feedback on these guidelines is highly encouraged. Please send any questions or comments to your application architect.
Your Company Name Here 3

2. C# Golden Rules
The following guidelines are applicable to all aspects C# development:
o Follow the style of existing code. Strive to maintain consistency within the code base of an application. If further
guidance is needed, look to these guidelines and the .NET framework for clarification and examples.
o Make code as simple and readable as possible. Assume that someone else will be reading your code.
o Prefer small cohesive classes and methods to large monolithic ones.
o Use a separate file for each class, struct, interface, enumeration, and delegate with the exception of those nested
within another class.
o Write the comments first. When writing a new method, write the comments for each step the method will perform
before coding a single statement. These comments will become the headings for each block of code that gets
implemented.
o Use liberal, meaningful comments within each class, method, and block of code to document the purpose of the code.
o Mark incomplete code with // TODO: comments. When working with many classes at once, it can be very easy to lose
a train of thought.
o Never hard code “magic” values into code (strings or numbers). Instead, define constants, static read-only variables,
and enumerations or read the values from configuration or resource files.
o Prefer while and foreach over other available looping constructs when applicable. They are logically simpler and
easier to code and debug.
o Use the StringBuilder class and it’s Append(), AppendFormat(), and ToString() methods instead of the string
concatenation operator (+=) for much more efficient use of memory.
o Be sure Dispose() gets called on IDisposable objects that you create locally within a method. This is most
commonly done in the finally clause of a try block. It’s done automatically when a using statement is used.
o Never present debug information to yourself or the end user via the UI (e.g. MessageBox). Use tracing and logging
facilities to output debug information.
o Gaps and exceptions to these guidelines should be discussed and resolved with your application architect.
Your Company Name Here 4

3. Formatting
3.1 Class Layout
Classes should be organized into regions within an application using a layout determined by your application architect.
These may be based on accessibility, type, or functionality. Consult your architect for the layout strategy used in your
application.
Example:
// Class layout based on accessibility
class Purchasing
{
#region Main
#region Public
#region Internal
#region Protected
#region Private
#region Extern
#region Designer Generated Code
}
Guidelines:
o Use the same layout consistently in all classes in an application.
o Omit regions if their associated class elements are not needed.
o The Designer Generated Code region created by Visual Studio’s Visual Designer should never be modified by
hand. It should contain only code generated by the designer.
3.2 Indicating Scope
Indicate scope when accessing all static and non-static class members. This provides a crystal clear indication of the
intended use of the member. VisualStudio.NET intellisense is automatically invoked when using this practice, providing a
list of all available class members. This helps prevent unnecessary typing and reduces the risk of typographic errors.
Example:
string connectionString = DataAccess.DefaultConnectionString;
float amount = this.CurrentAmount;
this.discountedAmount = this.CalculateDiscountedAmount( amount, this.PurchaseMethod );
Guidelines:
o Include the this keyword before all member fields, properties and methods.
o Include the name of the class before all static fields, constants, fields, and methods.
Your Company Name Here 5

3.5 Long lines of code
Comments and statements that extend beyond 80 columns in a single line can be broken up and indented for readability.
Care should be taken to ensure readability and proper representation of the scope of the information in the broken lines.
When passing large numbers of parameters, it is acceptable to group related parameters on the same line.
Example:
string Win32FunctionWrapper(
int arg1,
string arg2,
bool arg3 )
{
// Perform a PInvoke call to a win32 function,
// providing default values for obscure parameters,
// to hide the complexity from the caller
if( Win32.InternalSystemCall(
null,
arg1, arg2,
Win32.GlobalExceptionHandler,
0, arg3,
null )
{
return “Win32 system call succeeded.”;
}
else
{
return “Win32 system call failed.”;
}
}
Guidelines:
o When breaking parameter lists into multiple lines, indent each additional line one tab further than the starting line that
is being continued.
o Group similar parameters on the same line when appropriate.
o When breaking comments into multiple lines, match the indentation level of the code that is being commented upon.
o Consider embedding large string constants in resources and retrieving them dynamically using the .NET
ResourceManager class.
Your Company Name Here 7

4. Commenting
4.1 Intellisense Comments
Use triple slash ‘///’ comments for documenting the public interface of each class. This will allow Visual Studio.Net to pick
up the method’s information for Intellisense. These comments are required before each public, internal, and protected
class member and optional for private members.
4.2 End-Of-Line Comments
Use End-Of-Line comments only with variable and member field declarations. Use them to document the purpose of the
variable being declared.
Example:
private string name = string.Empty; // Name of control (defaults to blank)
4.3 Single Line Comments
Use single line comments above each block of code relating to a particular task within a method that performs a significant
operation or when a significant condition is reached. Comments should always begin with two slashes, followed by a
space.
Example:
// Compute total price including all taxes
float stateSalesTax = this.CalculateStateSalesTax( amount, Customer.State );
float citySalesTax = this.CalculateCitySalesTax( amount, Customer.City );
float localSalesTax = this.CalculateLocalSalesTax( amount, Customer.Zipcode );
float totalPrice = amount + stateSalesTax + citySalesTax + localSalesTax;
Console.WriteLine( “Total Price: {0}”, totalPrice );
4.4 // TODO: Comments
Use the // TODO: comment to mark a section of code that needs further work before release. Source code should be
searched for these comments before each release build.
4.5 C-Style Comments
Use c-style /*…*/ comments only for temporarily blocking out large sections of code during development and debugging.
Code should not be checked in with these sections commented out. If the code is no longer necessary, delete it. Leverage
your source control tools to view changes and deletions from previous versions of the code. If code must be checked in
with large sections commented out, include a // TODO: comment above the block commented out describing why it was
checked in that way.
Your Company Name Here 8

5. Capitalization & Naming
5.1 Capitalization
Follow the standard Naming Guidelines set by the .NET framework team by using only three capitalization styles: Pascal,
Camel, and Upper casing.
Examples:
Identifier Type Capitalization Style Example(s)
Abbreviations Upper ID, REF
Namespaces Pascal AppDomain, System.IO
Classes & Structs Pascal AppView
Constants & Enums Pascal TextStyles
Interfaces Pascal IEditableObject
Enum values Pascal TextStyles.BoldText
Property Pascal BackColor
Variables, and Attributes Pascal (public) WindowSize
Camel (private, protected, local) windowWidth, windowHeight
Methods Pascal (public, private, protected) ToString()
Camel (parameters) SetFilter(string filterValue)
Local Variables Camel recordCount
Guidelines:
o In Pascal casing, the first letter of an identifier is capitalized as well as the first letter of each concatenated word. This
style is used for all public identifiers within a class library, including namespaces, classes and structures, properties,
and methods.
o In Camel casing, the first letter of an identifier is lowercase but the first letter of each concatenated word is capitalized.
This style is used for private and protected identifiers within the class library, parameters passed to methods, and
local variables within a method.
o Upper casing is used only for abbreviated identifiers and acronyms of four letters or less.
5.2 Naming
Follow the standard set by the .NET framework team when it comes to naming. The 6. Programming section of this
document provides naming templates for each construct within the C# language. These templates can be used in
conjunction with the tables provided in Appendix A. Naming Parts & Pairs to yield meaningful names in most scenarios.
Your Company Name Here 9

6. Programming
6.1 Namespaces
Namespaces represent the logical packaging of component layers and subsystems. The declaration template for
namespaces is: CompanyName.ProjectOrDomainName.PackageName.SubsystemName.
Examples:
Microsoft.Data.DataAccess
Microsoft.Logging.Listeners
Guidelines:
o Project and package level namespaces will normally be predetermined by an application architect for each project.
o Use Pascal casing when naming Subsystem namespaces.
6.2 Classes & Structures
Classes and structures represent the ‘Nouns’ of a system. As such, they should be declared using the following template:
Noun + Qualifier(s). Classes and structures should declared with qualifiers that reflect their derivation from a base class
whenever possible.
Examples:
CustomerForm : Form
CustomerCollection : CollectionBase
Guidelines:
o Use Pascal casing when naming classes and structures.
o Classes and structures should be broken up distinct #regions as previously described in the class layout guidelines.
o All public classes and their methods should be documented using the Intellisense triple slash ‘///’ comments built into
Visual Studio.Net. Use this comment style to document the purpose of the class and its methods.
o Default values for fields should be assigned on the line where the field is declared. These values are assigned at
runtime just before the constructor is called. This keeps code for default values in one place, especially when a class
contains multiple constructors.
6.3 Interfaces
Interfaces express behavior contracts that derived classes must implement. Interface names should use Nouns, Noun
Phrases, or Adjectives that clearly express the behavior that they declare.
Examples:
IComponent
IFormattable
ITaxableProduct
Guidelines:
Your Company Name Here 10

o Prefix interface names with the letter ‘I’.
o Use Pascal casing when naming interfaces.
6.4 Constants
Constants and static read-only variables should be declared using the following template: Adjective(s) + Noun +
Qualifier(s)
Example:
public const int DefaultValue = 25;
public static readonly string DefaultDatabaseName = “Membership”;
Guidelines:
o Use Pascal casing when naming constants and static read only variables.
o Prefer the use of static readonly over const for public constants whenever possible. Constants declared using
const are substituted into the code accessing them at compile time. Using static readonly variables ensures that
constant values are accessed at runtime. This is safer and less prone to breakage, especially when accessing a
constant value from a different assembly.
6.5 Enumerations
Enumerations should be declared using the following template: Adjective(s) + Noun + Qualifier(s)
Example:
///
/// Enumerates the ways a customer may purchase goods.
///
[Flags]
public enum PurchaseMethod
{
All = ~0,
None = 0,
Cash = 1,
Check = 2,
CreditCard= 4,
DebitCard = 8,
Voucher = 16,
}
Guidelines:
o Use Pascal casing when naming enumerations.
o Use the [Flags] attribute only to indicate that the enumeration can be treated as a bit field; that is, a set of flags.
6.6 Variables, Fields & Parameters
Variables, fields, and parameters should be declared using the following template: Adjective(s) + Noun + Qualifier(s)
Examples:
int lowestCommonDenominator = 10;
float firstRedBallPrice = 25.0f;
Your Company Name Here 11

Guidelines:
o Use Camel casing when naming variables, fields, and parameters.
o Define variables as close as possible to the first line of code where they are used.
o Declare each variable and field on a separate line. This allows the use of End-Of-Line comments for documenting
their purpose.
o Assign initial values whenever possible. The .NET runtime defaults all unassigned variables to 0 or null automatically,
but assigning them proper values will alleviate unnecessary checks for proper assignment elsewhere in code.
o Avoid meaningless names like i, j, k, and temp. Take the time to describe what the object really is (e.g. use
index instead of i; use swapInt instead of tempInt).
o Use a positive connotation for boolean variable names (e.g. isOpen as opposed to notOpen).
6.7 Properties
Properties should be declared using the following template: Adjective(s) + Noun + Qualifier(s)
Examples:
public TotalPrice
{
get
{
return this.totalPrice;
}
set
{
// Set value and fire changed event if new value is different
if( !object.Equals( value, this.totalPrice )
{
this.totalPrice = value;
this.OnTotalPriceChanged();
}
}
}
Guidelines:
o Use the common prefixes for inspection properties (properties that return query information about an object). See
Appendix A. Naming Parts & Pairs for common prefixes.
o When there is a property setter that sets another property:
• If the code in the other property sets a private member field in the same class, the field should be set directly,
without calling the property setter for that field.
• If a property setter sets a private field that would normally be set via another property setter, the originating setter
is responsible for firing any events the other setter would normally fire (e.g. Changed events).
• If a value that needs to be set that does NOT correspond to a private field, then an appropriate property setter or
method should be called to set the value.
6.8 Methods
Methods should be named using the following format: Verb + Adjective(s) + Noun + Qualifier(s)
Your Company Name Here 12

Example:
private Ball FindRedCansByPrice(
float price,
ref int canListToPopulate,
out int numberOfCansFound )
Guidelines:
o Parameters should be grouped by their mutability (from least to most mutable) as shown in the example above.
o If at all possible, avoid exiting methods from their middles. A well written method should only exit from one point: at its
end.
o Avoid large methods. As a method’s body approaches 20 to 30 lines of code, look for blocks that could be split into
their own methods and possibly shared by other methods.
o If you find yourself using the same block of code more than once, it’s a good candidate for a separate method.
o Group like methods within a class together into a region and order them by frequency of use (i.e. more frequently
called methods should be near the top of their regions.
6.9 Event Handlers
Event handlers should be declared using the following format: ObjectName_EventName
Example:
private HelpButton_Click( object sender, EventArgs e )
6.10 Error Handling
Use exceptions only for exceptional cases, not for routine program flow. Exceptions have significant performance
overhead.
Guidelines:
o Pass a descriptive string into the constructor when throwing an exception.
o Use grammatically correct error messages, including ending punctuation. Each sentence in the description string of an
exception should end in a period.
o If a property or method throws an exception in some cases, document this in the comments for the method. Include
which exception is thrown and what causes it to be thrown.
• Example: Comment for Order.TotalCost property might read "Gets or sets the total cost of an Order. If the
TotalCost property is set when the cost should be calculated, an InvalidOperationException is thrown."
o Use the following exceptions if appropriate:
• ArgumentException (and ArgumentNull, ArgumentOutOfRange, IndexOutOfRange): Used when checking
for valid input parameters to method.
• InvalidOperationException: Used when a method call is invalid for the current state of an object.
Your Company Name Here 13

Example: TotalCost cannot be set if the cost should be calculated. If the property is set and it fails this
rule, an InvalidOperationException is thrown.
• NotSupportedException: Used when a method call is invalid for the class.
Example: Quantity, a virtual read/write property, is overridden by a derived class. In the derived class,
the property is read-only. If the property is set, a NotSupportedException is thrown.
• NotImplementedException: Used when a method is not implemented for the current class.
Example: A interface method is stubbed in and not yet implemented. This method should throw a
NotImplementedException.
o Derive your own exception classes for a programmatic scenarios. All new derived exceptions should be based upon
the core Exception class.
Example: DeletedByAnotherUserException : Exception. Thrown to indicate a record being modified has
been deleted by another user.
o Rethrow caught exceptions correctly.
The following example throws an exception caught and rethrown incorrectly:
catch( Exception ex )
{
LogManager.Publish( ex );
throw ex; // INCORRECT – we lose the call stack of the exception
}
We log all unhandled exceptions in our applications, but may sometimes throw them again to let the higher level
systems determine how to proceed. The problem comes in with the throw – it works much better to do this:
catch( Exception ex )
{
LogManager.Publish( ex );
throw; // CORRECT ­ rethrows the exception we just caught
}
Notice the absence of an argument to the throw statement in the second variation.
The difference between these two variations is subtle but important. With the first example, the higher level caller
isn’t going to get all the information about the original error. The call stack in the exception is replaced with a new
call stack that originates at the “throw ex” statement – which is not what we want to record. The second example
is the only one that actually re-throws the original exception, preserving the stack trace where the original error
occurred.
Your Company Name Here 14