Difference between revisions of "Front-End Standard"
Line 203: | Line 203: | ||
|} | |} | ||
− | ==Coding Style== | + | ===Coding Style=== |
{| class="wikitable" border="1" | {| class="wikitable" border="1" | ||
Line 282: | Line 282: | ||
|} | |} | ||
− | ==Naming Conventions== | + | ===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. | 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. | ||
Line 297: | Line 297: | ||
*Do not use Hungarian Notation! | *Do not use Hungarian Notation! | ||
− | Example: strName or iCount | + | '''Example:''' strName or iCount |
*Avoid using abbreviations unless the full name is excessive. | *Avoid using abbreviations unless the full name is excessive. | ||
Line 306: | Line 306: | ||
*Avoid naming conflicts with existing .NET Framework namespaces, or types. | *Avoid naming conflicts with existing .NET Framework namespaces, or types. | ||
*Avoid adding redundant or meaningless prefixes and suffixes to identifiers | *Avoid adding redundant or meaningless prefixes and suffixes to identifiers | ||
− | Example: | + | '''Example:''' |
// Bad! | // Bad! | ||
public enum ColorsEnum {…} | public enum ColorsEnum {…} | ||
Line 313: | Line 313: | ||
*Do not include the parent class name within a property name. | *Do not include the parent class name within a property name. | ||
− | Example: Customer.Name NOT Customer.CustomerName | + | '''Example:''' Customer.Name NOT Customer.CustomerName |
*Try to prefix Boolean variables and properties with “Can”, “Is” or “Has”. | *Try to prefix Boolean variables and properties with “Can”, “Is” or “Has”. | ||
*Append computational qualifiers to variable names like Average, Count, Sum, Min, and Max where appropriate. | *Append computational qualifiers to variable names like Average, Count, Sum, Min, and Max where appropriate. | ||
*When defining a root namespace, use a Product, Company, or Developer Name as the root. Example: SmartHCM.StringUtilities | *When defining a root namespace, use a Product, Company, or Developer Name as the root. Example: SmartHCM.StringUtilities | ||
+ | |||
+ | {| class="wikitable" border="1" | ||
+ | |- | ||
+ | ! Identifier | ||
+ | ! Naming Convention | ||
+ | |- | ||
+ | | Project File | ||
+ | | Pascal Case.Always match Assembly Name & Root Namespace.Example:SmartHCM.Web.csproj -> SmartHCM.Web.dll -> namespace | ||
+ | SmartHCM.Web | ||
+ | |- | ||
+ | | Source File | ||
+ | | Pascal Case.Always match Class name and file name.Avoid including more than one Class, Enum (global), or Delegate (global) per file. Use a descriptive file name when containing multiple Class, Enum, or Delegates.Example:MyClass.cs => public class MyClass{…} | ||
+ | |- | ||
+ | | ResourceorEmbedded File | ||
+ | | Try to use Pascal Case.Use a name describing the file contents. | ||
+ | |- | ||
+ | | Namespace | ||
+ | | Pascal Case.Try to partially match Project/Assembly Name.Example:namespace SmartHCM.Web{…} | ||
+ | |- | ||
+ | | Class or Struct | ||
+ | | Pascal Case.Use a noun or noun phrase for class name.Add an appropriate class-suffix when sub-classing another type when possible.Examples: | ||
+ | private class MyClass {…}internal class SpecializedAttribute : Attribute {…}public class CustomerCollection : CollectionBase {…} | ||
+ | |- | ||
+ | | | ||
+ | | public class CustomEventArgs : EventArgs {…}private struct ApplicationSettings{…} | ||
+ | |- | ||
+ | | Interface | ||
+ | | Pascal Case.Always prefix interface name with capital “I”.Example:interface ICustomer{…} | ||
+ | |- | ||
+ | | Generic Class & Generic Parameter Type | ||
+ | | Always use a single capital letter, such as T or K.Example:public class FifoStack<T>{public void Push(<T> obj){…}public <T> Pop(){…}} | ||
+ | |- | ||
+ | | Method | ||
+ | | Pascal Case.Try to use a Verb or Verb-Object pair.Example:public void Execute() {…}private string GetAssemblyVersion(Assembly target) {…} | ||
+ | |- | ||
+ | | Property | ||
+ | | Pascal Case.Property name should represent the entity it returns. Never prefix property names with“Get” or “Set”.Example:public string Name{get{…}set{…}} | ||
+ | |- | ||
+ | | Field(Public, Protected,or Internal) | ||
+ | | Pascal Case.Avoid using non-private Fields!Use Properties instead.Example:public string Name;protected IList InnerList; | ||
+ | |- | ||
+ | | Field (Private) | ||
+ | | Camel Case and prefix with a single underscore (_) character.Example:private string _name; | ||
+ | |- | ||
+ | | Constant orStatic Field | ||
+ | | Treat like a Field.Choose appropriate Field access-modifier above. | ||
+ | |- | ||
+ | | Enum | ||
+ | | Pascal Case (both the Type and the Options).Add the FlagsAttribute to bit-mask multiple options.Example:public enum CustomerTypes{Consumer,Commercial} | ||
+ | |- | ||
+ | | Delegate or Event | ||
+ | | Treat as a Field.Choose appropriate Field access-modifier above. | ||
+ | |- | ||
+ | | | ||
+ | | Example:public event EventHandler LoadPlugin; | ||
+ | |- | ||
+ | | Variable (inline) | ||
+ | | Camel Case.Avoid using single characters like “x” or “y” except in FOR loops.Avoid enumerating variable names like text1, text2, text3 etc. | ||
+ | |- | ||
+ | | Parameter | ||
+ | | Camel Case.Example:public void Execute(string commandText, int iterations){…} | ||
+ | |} | ||
+ | |||
+ | ==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 source code in order to create readable, clear, and consistent code that is easy to understand and maintain. | ||
+ | |||
+ | ===Formatting=== | ||
+ | |||
+ | *Never declare more than 1 namespace per file. | ||
+ | *Avoid putting multiple classes in a single file. | ||
+ | *Always place curly braces ({ and }) on a new line. | ||
+ | *Curly braces ( {} ) should be in the same level as the code outside the braces. | ||
+ | Example: | ||
+ | if ( … ) | ||
+ | { | ||
+ | // Do something! | ||
+ | // … | ||
+ | return false; | ||
+ | } | ||
+ | *Always use curly braces ({ and }) in conditional statements. | ||
+ | *Always use a Tab & Indention size of 4. | ||
+ | *Use one blank line to separate logical groups of code. | ||
+ | *There should be one and only one single blank line between each method inside the class. | ||
+ | *Declare each variable independently – not in the same statement. | ||
+ | *Place namespace “using” statements together at the top of file. Group .NET namespaces above custom namespaces. | ||
+ | *Group internal class implementation by type in the following order: | ||
+ | a. Member variables. | ||
+ | b. Constructors & Finalizers. | ||
+ | c. Nested Enums, Structs, and Classes. | ||
+ | d. Properties | ||
+ | e. Methods | ||
+ | *Sequence declarations within type groups based upon access modifier and visibility: | ||
+ | a. Public | ||
+ | b. Protected | ||
+ | c. Internal | ||
+ | d. Private | ||
+ | |||
+ | *Segregate interface Implementation by using #region statements. | ||
+ | *Use #region to group related pieces of code together. If you use proper grouping using #region, the page should like this when all definitions are collapsed. | ||
+ | '''Example:''' | ||
+ | |||
+ | *Recursively indent all code blocks contained within braces. | ||
+ | *Use white space (CR/LF, Tabs, etc) liberally to separate and organize code. | ||
+ | |||
+ | ===Code Commenting=== | ||
+ | |||
+ | *All comments should be written in the same language, be grammatically correct, and contain appropriate punctuation. | ||
+ | *Use // or /// but never /* … */ | ||
+ | *Do not “flowerbox” comment blocks. | ||
+ | '''Example:''' | ||
+ | // *************************************** | ||
+ | // Comment block | ||
+ | // *************************************** | ||
+ | *Use inline-comments to explain assumptions, known issues, and algorithm insights. | ||
+ | *Do not use inline-comments to explain obvious code. Well written code is self documenting. | ||
+ | *Only use comments for bad code to say “fix this code” – otherwise remove, or rewrite the code! | ||
+ | *Include comments using Task-List keyword flags to allow comment-filtering. | ||
+ | '''Example:''' | ||
+ | // TODO: Place Database Code Here | ||
+ | // UNDONE: Removed P\Invoke Call due to errors | ||
+ | // HACK: Temporary fix until able to refactor | ||
+ | 24. Always apply C# comment-blocks (///) to public, protected, and internal declarations. | ||
+ | 25. Only use C# comment-blocks for documenting the API. | ||
+ | 26. Always include <summary> comments. Include <param>, <return>, and <exception> comment sections where applicable. | ||
+ | 27. Include <see cref=””/> and <seeAlso cref=””/> where possible. | ||
+ | 28. 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: | ||
+ | /// <code><![CDATA[ | ||
+ | /// <configuration> | ||
+ | /// <appSettings> | ||
+ | /// <add key=”mySetting” value=”myValue”/> | ||
+ | /// </appSettings> | ||
+ | /// </configuration> | ||
+ | /// ]]></code> | ||
+ | /// </example> | ||
+ | |||
+ | ===Language Usage=== | ||
+ | ===General=== | ||
+ | *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) | ||
+ | {…} | ||
+ | *Do not use the default (“1.0.*”) versioning scheme. Increment the AssemblyVersionAttribute value manually. | ||
+ | *Set the ComVisibleAttribute to false for all assemblies. | ||
+ | *Only selectively enable the ComVisibleAttribute for individual classes when needed. | ||
+ | '''Example:''' | ||
+ | [assembly: ComVisible(false)] | ||
+ | [ComVisible(true)] | ||
+ | public MyClass | ||
+ | {…} | ||
+ | *Consider factoring classes containing unsafe code blocks into a separate assembly. | ||
+ | *Avoid mutual references between assemblies. | ||
+ | *Use enum wherever required. Do not use numbers or strings to indicate discrete values. | ||
+ | '''Example:''' | ||
+ | // Bad! |
Revision as of 07:56, 30 April 2015
Contents
Introduction
This document describes rules and recommendations for developing applications in .NET 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.
This document covers Naming Conventions, Coding Style, Language Usage, Object Model Design and Tips for developers.
Document Convention
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 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.
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 { … }
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.”
Flags
The following flags are used to help clarify or categorize certain statements:
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.
Naming Conventions
- “c” = camelCase
- “P” = PascalCase
- “_” = Prefix with _Underscore
- “x” = Not Applicable.
Identifier | Public | Protected | Internal | Private | Notes |
---|---|---|---|---|---|
Project File | P | x | x | x | Match Assembly & Namespace. |
Source File | P | x | x | x | Match contained class. |
Other Files | P | x | x | x | Apply where possible. |
Namespace | P | x | x | x | Partial Project/Assembly match. |
Class or Struct | P | P | P | P | Add suffix of subclass. |
Interface | P | P | P | P | Prefix with a capital I. |
Source FileGeneric Class | P | P | P | P | Use T or K as Type identifier. |
Method | P | P | P | P | Use a Verb or Verb-Object pair |
Property | P | P | P | P | Do not prefix with Get or Set. |
Field | P | P | v | _c | Only use Private fields.No Hungarian Notation! |
Constant | P | P | P | _c | |
Static Field | P | P | P | _c | Only use Private fields. |
Enum | P | P | P | P | Options are also Pascal Case. |
Delegate | P | P | P | P | |
Event | P | x | x | x | |
Inline Variable | x | x | x | c | Avoid single-character and enumerated names. |
Parameter | P | x | x | c |
Coding Style
Code | Style |
---|---|
Source Files | One Namespace per file and one class per file. |
Curly Braces | On new line. Always use braces when optional. |
Indention | Use tabs with size of 4. |
Comments | Use // or /// but not /* … */ and do not flowerbox. |
Variables | One variable per declaration. |
Language Usage
Code | Style |
---|---|
Native Data Types | Use built-in C# native data types vs .NET CTS types. (Use int NOT Int32) |
Enums | Avoid changing default type. |
Generics | Prefer Generic Types over standard or strong-typed classes. |
Properties | Never prefix with Get or Set. |
Methods | Use a maximum of 7 parameters. |
base and this | Use only in constructors or within an override. |
Ternary conditions | Avoid complex conditions. |
for each statements | Do not modify enumerated items within a foreach statement. |
Conditionals | Avoid evaluating Boolean conditions against true or false.No embedded assignment.Avoid embedded method invocation. |
Exceptions | Do not use exceptions for flow control.Use throw; not throw e; when re-throwing.Only catch what you can handle.Use validation to avoid exceptions.Derive from Execption not ApplicationException. |
Events | Always check for null before invoking. |
Locking | Use lock() not Monitor.Enter().Do not lock on an object type or “this”.Do lock on private objects. |
Dispose() & Close() | Always invoke them if offered, declare where needed. |
Finalizers | Avoid.Use the C# Destructors.Do not create Finalize() method. |
Assembly Version | Increment manually. |
ComVisibleAttribute | Set to false for all assemblies |
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.
General Guidelines
- Always use Camel Case or Pascal Case names.
- Avoid ALL CAPS and all lowercase names. Single lowercase words or letters are acceptable.
- Do not create declarations of the same type (namespace, class, method, property, field, or parameter) and access modifier (protected, public, private, internal) that vary only by capitalization.
- Do not use names that begin with a numeric character.
- Do add numeric suffixes to identifier names.
- Always choose meaningful and specific names.
- Variables and Properties should describe an entity not the type or size.
- Do not use Hungarian Notation!
Example: strName or iCount
- Avoid using abbreviations unless the full name is excessive.
- Avoid abbreviations longer than 5 characters.
- Any Abbreviations must be widely known and accepted.
- Use uppercase for two-letter abbreviations, and Pascal Case for longer abbreviations.
- Do not use C# reserved words as names.
- Avoid naming conflicts with existing .NET Framework namespaces, or types.
- Avoid adding redundant or meaningless prefixes and suffixes to identifiers
Example: // Bad! public enum ColorsEnum {…} public class CVehicle {…} public struct RectangleStruct {…}
- Do not include the parent class name within a property name.
Example: Customer.Name NOT Customer.CustomerName
- Try to prefix Boolean variables and properties with “Can”, “Is” or “Has”.
- Append computational qualifiers to variable names like Average, Count, Sum, Min, and Max where appropriate.
- When defining a root namespace, use a Product, Company, or Developer Name as the root. Example: SmartHCM.StringUtilities
Identifier | Naming Convention |
---|---|
Project File | Pascal Case.Always match Assembly Name & Root Namespace.Example:SmartHCM.Web.csproj -> SmartHCM.Web.dll -> namespace
SmartHCM.Web |
Source File | Pascal Case.Always match Class name and file name.Avoid including more than one Class, Enum (global), or Delegate (global) per file. Use a descriptive file name when containing multiple Class, Enum, or Delegates.Example:MyClass.cs => public class MyClass{…} |
ResourceorEmbedded File | Try to use Pascal Case.Use a name describing the file contents. |
Namespace | Pascal Case.Try to partially match Project/Assembly Name.Example:namespace SmartHCM.Web{…} |
Class or Struct | Pascal Case.Use a noun or noun phrase for class name.Add an appropriate class-suffix when sub-classing another type when possible.Examples:
private class MyClass {…}internal class SpecializedAttribute : Attribute {…}public class CustomerCollection : CollectionBase {…} |
public class CustomEventArgs : EventArgs {…}private struct ApplicationSettings{…} | |
Interface | Pascal Case.Always prefix interface name with capital “I”.Example:interface ICustomer{…} |
Generic Class & Generic Parameter Type | Always use a single capital letter, such as T or K.Example:public class FifoStack<T>{public void Push(<T> obj){…}public <T> Pop(){…}} |
Method | Pascal Case.Try to use a Verb or Verb-Object pair.Example:public void Execute() {…}private string GetAssemblyVersion(Assembly target) {…} |
Property | Pascal Case.Property name should represent the entity it returns. Never prefix property names with“Get” or “Set”.Example:public string Name{get{…}set{…}} |
Field(Public, Protected,or Internal) | Pascal Case.Avoid using non-private Fields!Use Properties instead.Example:public string Name;protected IList InnerList; |
Field (Private) | Camel Case and prefix with a single underscore (_) character.Example:private string _name; |
Constant orStatic Field | Treat like a Field.Choose appropriate Field access-modifier above. |
Enum | Pascal Case (both the Type and the Options).Add the FlagsAttribute to bit-mask multiple options.Example:public enum CustomerTypes{Consumer,Commercial} |
Delegate or Event | Treat as a Field.Choose appropriate Field access-modifier above. |
Example:public event EventHandler LoadPlugin; | |
Variable (inline) | Camel Case.Avoid using single characters like “x” or “y” except in FOR loops.Avoid enumerating variable names like text1, text2, text3 etc. |
Parameter | Camel Case.Example:public void Execute(string commandText, int iterations){…} |
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 source code in order to create readable, clear, and consistent code that is easy to understand and maintain.
Formatting
- Never declare more than 1 namespace per file.
- Avoid putting multiple classes in a single file.
- Always place curly braces ({ and }) on a new line.
- Curly braces ( {} ) should be in the same level as the code outside the braces.
Example: if ( … ) { // Do something! // … return false; }
- Always use curly braces ({ and }) in conditional statements.
- Always use a Tab & Indention size of 4.
- Use one blank line to separate logical groups of code.
- There should be one and only one single blank line between each method inside the class.
- Declare each variable independently – not in the same statement.
- Place namespace “using” statements together at the top of file. Group .NET namespaces above custom namespaces.
- Group internal class implementation by type in the following order:
a. Member variables. b. Constructors & Finalizers. c. Nested Enums, Structs, and Classes. d. Properties e. Methods
- Sequence declarations within type groups based upon access modifier and visibility:
a. Public b. Protected c. Internal d. Private
- Segregate interface Implementation by using #region statements.
- Use #region to group related pieces of code together. If you use proper grouping using #region, the page should like this when all definitions are collapsed.
Example:
- Recursively indent all code blocks contained within braces.
- Use white space (CR/LF, Tabs, etc) liberally to separate and organize code.
Code Commenting
- All comments should be written in the same language, be grammatically correct, and contain appropriate punctuation.
- Use // or /// but never /* … */
- Do not “flowerbox” comment blocks.
Example: // *************************************** // Comment block // ***************************************
- Use inline-comments to explain assumptions, known issues, and algorithm insights.
- Do not use inline-comments to explain obvious code. Well written code is self documenting.
- Only use comments for bad code to say “fix this code” – otherwise remove, or rewrite the code!
- Include comments using Task-List keyword flags to allow comment-filtering.
Example:
// TODO: Place Database Code Here
// UNDONE: Removed P\Invoke Call due to errors
// HACK: Temporary fix until able to refactor
24. Always apply C# comment-blocks (///) to public, protected, and internal declarations.
25. Only use C# comment-blocks for documenting the API.
26. Always include <summary> comments. Include <param>, <return>, and <exception> comment sections where applicable.
27. Include <see cref=””/> and <seeAlso cref=””/> where possible.
28. 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:
/// <![CDATA[
/// <configuration>
/// <appSettings>
/// <add key=”mySetting” value=”myValue”/>
/// </appSettings>
/// </configuration>
/// ]]>
/// </example>
Language Usage
General
- 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) {…}
- Do not use the default (“1.0.*”) versioning scheme. Increment the AssemblyVersionAttribute value manually.
- Set the ComVisibleAttribute to false for all assemblies.
- Only selectively enable the ComVisibleAttribute for individual classes when needed.
Example: [assembly: ComVisible(false)] [ComVisible(true)] public MyClass {…}
- Consider factoring classes containing unsafe code blocks into a separate assembly.
- Avoid mutual references between assemblies.
- Use enum wherever required. Do not use numbers or strings to indicate discrete values.
Example: // Bad!