Development Naming Standards

Print Friendly, PDF & Email

Naming Conventions Standards

Naming Convention Definition:

A collection of standards for ensuring consistent readability of all developed code

Naming Convention Justification:

This standard is first for a very good reason: It is the most important standard of them all. Conforming to a best practice, Corporate wide development naming convention will have the greatest return on investment for any company.

It will create a development environment that reduces the time it will take any developer to clearly understand the intent of the code. This standard will help set the stage for all the other standards that The Modern Developer will follow.

There are three types of notation currently used in development:

  1. Pascal Casing – The first character of each word is capitalized without any spaces: MyClass()

  2. Camel Casing – Capitalization of each word except the first without any spaces: myProperty

  3. Hungarian Notation (obsolete ) – Hungarian notation utilizes a defined set of pre and postfix which are applied to names to reflect the type and scope of a variable.  Hungarian notation is now considered obsolete. Hungarian Notation will not be used for any naming convention.

The Modern Developer’s Development Naming Convention (DNC) standards will define specific uses of the two casings above: Pascal and Camel Casings. This will enhance Code understanding and the underlying intent of the Software entities.

Naming Conventions:

+Namespaces
Case Description Example
Pascal The naming convention for the assembly will define the root namespace.
The folder structure of an assembly will always define the appended namespaces. 		 Best Practice:
[DomainEntityName].[AssemblyName].[Purpose]

  Example:
namespace Widgets.CustomerContacts.Data
namespace Widgets.CustomerContacts.Controllers
+Classes
Case Description Example
Pascal One Class per file, Class name is file name with a .cs extension.
Classes are named as Nouns or Noun Phrases. Classes are “THINGS” and should not be named as Verbs. Verbs are “ACTIONS”. 		 Best Practice:
[Access Modifier] class [Class Name]

  Example:
public class CustomerContactsFactory
protected class CustomerContactsHelpers
+Interfaces
Case Description Example
Pascal Prefix with “I” and then Pascal casing.
Don’t name an Interface with the same name as a Class Type as there should be more than one Concrete Class Type implementing an Interface. 		 Best Practice:
public interface I[InterfaceName]
internal interface I[InterfaceName]

 Acceptable Violation:
Pascal can be violated to support Business Domain Names when required

 Example:
public interface IData
internal interface IStubData

 Violation Exception Example:
public interface IFBIData

+Properties
Case Description Example
Pascal or Modified Camel Class Properties can be Private or Public. If a Property Method, an auto-property, is publically exposed it will be in Pascal Case
If it is a Private Class scoped property it will be Camel Case with an appended underscore.
See the more detailed explanation in other Fields Standards. 		 Best Practice:
public [Type] [PropertyName]{get; set;}
private ststic [Type] [PropertyName]{get; set;}

 Example:
public List Contacts {get; set;}
private static ClientWrapper _wrapper {get; set;}
+Method / Function
Case Description Example
Pascal C# uses Methods to encapsulate functionality. Methods are sometimes referred to as Functions, generally if they return Void.
A Name should never describe how the Method accomplishes its intent. A Name describes “What” it does not “How” it does it.
Methods should use a Verb or Verb a phrase in Pascal case to convey an “ACTION”.
Methods should not be named as “THINGS”. 		 Best Practice for a Public Class Method:
public [Type] [MethodName]([ParamType] [ParamName])

 Best Practice for a Private Class Method:
private void [MethodName]([ParamType] [ParamName]

 Example for Public Method:
public Response GetContacts(Request viewRequest)
the ‘Response’ Object for consumption

 Example for Private Class Level Function:
private void SetContactRole(Role newContactRole)
Sets a Class Level Property in the implementation that has already initialized in the Constructor

 Naming Convention Violation Example:
public string GetCustomerIdForEmailAds()
Never reveal implementation usage details: ‘ForEmailAds’

+Public Fields / Data Members
Case Description Example
Pascal A Class scope level variable that has an Access Modifier of public is never allowed. This exposes the Data Member to the consuming module and violates one of the Pillars of Object Oriented Programming: Encapsulation.
The consuming module could change the intent of the use of the data and corrupt the result and performance of the underlying Class.
Use a Property Method with a private backing field to expose the intended data result outside the class. An Auto-Property will do this for you behind the scene. 		 Best Practice for Public Data Property Method:
public [Type] [PropertyName]{get; set;}

 Violation of Encapsulation Data Member:
public [Type] [PropertyName];

 Example for Public Data Property Method:
public int CustomerId {get; set;}

 Example for Private Data Member:
private int CustomerId;
This is acceptable but is not Best Practice as it removes all the power of a Method from the private Class Level variable

 Encapsulation Violation Example:
public string CustomerId;
Never expose the possibility for a Consuming Client to modify the intent of your code externally

+Private Fields / Data Members
Case Description Example
Camel A Class scope level variable that has an Access Modifier of private is allowed. This does not expose the Data Member to the consuming module and complies with encapsulation.
Use a Property Method with a private backing field to expose the intended data result outside the class. An Auto-Property will do this for you behind the scene.
Use an underscore ( _ ) character to denote that it is a Class Level private variable whenever it is used.
It is proper to name a Property the same as its strongly types object
Boolean properties should use affirmative phrasing. Use is, can and have to add value intent to the name.
Static keyword should be used when the property is set and never changed to ensure that it is run only once
The readonly keyword should be used to set the property as a constant enforced at runtime. Use it if the value is not known at compilation time. Use the constructor to set readonly properties.
The readonly keyword should be used in place of Constants. Constant should be avoided. SCREAMING Caps should never be used in modern programming 		 Best Practice for Private Data Property Method:
private static [Type] _[PropertyName] {get; set;}

 Violation of Data Member Best Practice Naming:
public [Type] _[PropertyNameVERB];

 Acceptable Naming Violation Example:
private static string _componentName;
Not Best Practice as it does not give the Data Member the power of a C# Method for Instantiation and validations.
This will not be treated as a Code Standard violation but is strongly discouraged

 Best Practice Example:
private static string _componentName {get; set;}
Best Practice as it does give the Data Member the power of a C# Method. A private backing field is automatically created and managed for you.

 Best Practice Typed Object Example:
private Contacts _contacts {get; set;}
This is the most common use case

 Best Practice for Boolean Objects Example:
private bool _isContactActive {get; set;}
private bool _canBeDeleted {get; set;}
private bool _hasAEndDate {get; set;}

 Best Practice Static Use Example:
private static string _componentName {get; set;}

 Best Practice Read Only Use Example:
private readonly int seedCount = 1;
Constant Use Replacement. Better performance at Run-time

 Naming Violation Example:
public string getCustomerId {get; set;}
Never name a property the same as a consuming method. It violates the Noun / Verb rule and it cause ambiguity of intent
+Enums
Case Description Example
Pascal Enums are Data Types that allow you to assign an indexer integer to a Pascal notated string.
Enums help to eliminate “Magic Strings” in code and guarantees that typos do not occur.
Enums can be “One and Only One” or they can be configured as a “One or More” using the Enum Flag attribute.
Single Enums are NEVER Plural
By setting the values as they are in the example you allow the CLR to run more efficiently by doing a binary operation to extract the result rather than a lengthy algorithm function to find the desired result.
Flag Enums are ALWAYS Plural 		 Best Practice for Guaranteed Single Value Use:
public enum [EnumName]{[[EnumName1],[EnumName2],[EnumNameN]}
Indexes are automatically created that are 0 based

 Best Practice Enum for Guaranteed Single Value Use Example:
public enum MessageTag
{
ContactsFailure, // 0 index
ContactsException, // 1 index
ContactsNotFound // 2 index
}

 Best Practice Enum for No Guaranteed Single Value Use Example:
public enum MessageTag
{
None,
ContactsFailure,
ContactsException,
ContactsNotFound
}

Best Practice states that for Enums that could be accessed and not find a member that the default value of 0 should be defined

 Best Practice for Possible Multiple Value Use Example:
[Flags] public enum MessageTags
{
None = 1, // 0001
ContactsException = 2 // 0010
ContactsNotFound = 4 // 0100
ContactsFound = 8 // 1000
}

Notice the Binary Bit shift from least significant digit to most significant digit. This gives the Run-time a very efficient means of assessing multiple Enums using the [Flags] attribute.
+Events / Delegates
Case Description Example
Pascal Events are named as Verbs or Verb Phrases. Events are “ACTIONS” and should not be named as Nouns.
Use present and past tense when it adds understanding of intent: “Closing” the “Closed”
Delegates used as types of Events are Event Handlers and should use the “EventHandler” suffix. Parameters of Event Handlers are always “Object sender” and “EventArgs e”
Name all Argument Class Types with the “EventArgs” suffix. Use strongly typed object to pass in multiple parameter arguments. 		 Best Practice:
public event [EventHandlerName] [EventName]
public EventArgs [EventArgsVariableName] = null
public delegate void [EventHandlerName]([Type] sender, EventArgs e);

 Event and Delegate Example for a Best Practice Event ‘Bp’:
public event BpHandler Bp;
public EventArgs e = null;
public delegate void BpHandler(Tips sender, EventArgs e);
‘Tips’ is the Type of the Sender Subscriber;
+Field Variables
Case Description Example
Camel Method level private data entities are variable fields. They are always Camel notation without an underscore. This designates them as Method scoped level Data Members.
Use the var keyword if the right side of the equals (=) operator clearly defines the C# Type. This helps to reduce code “Noise” and clutter and makes the code more readable.
Do not use “Temp” variables. A temp variable is a declared data member field that is only used once. Instead, copy the value used to set the temp variable and paste it into the location of the use of the temp variable..
Temp variables become Garbage collection candidates immediately after instantiation needlessly. This puts an undue strain on the Garbage Collector and reduced overall performance. 		 Best Practice Primitive Variable Declaration Practice:
var [variableName] = [VariableValue]

 Best Practice Typed Variable Declaration Practice:
var [variableName] = new [VariableType]()

 Undesirable Practice Typed Variable Declaration Practice:
[VariableType] [variableName] = new [VariableType]()

  Best Practice Primitive Variable Declaration Practice Examples:
var message = “This is a Test Message”;
var messageCount = 3;

  Undesirable Practice Primitive Variable Declaration Practice Examples:
string message = “This is a Test Message”;
int messageCount = 3;

  Undesirable Practice using a Temp Variable Examples:
var contactCount = GetCount();
var contacts = CreateContactsList(contactCount);

  Best Practice without a Temp Variable Examples:
var contacts = CreateContactsList(GetCount());
+Constants
Case Description Example
Pascal Naming Constants is an interesting philosophical battle within the Development Community. It revolves around the use of SCREAMING_CAPS.
One or the other is generally OK. Predominate belief is that SCREAMING_CAPS are ugly. They do visually distinguish them for other variables
There is no reason to have a Constant “Stand Out” as it is just a Class Level Private variable type that is less desirable than the Read Only equivalent for Run-time performance.
The Modern Developer Standards is setting the standard as Pascal Without SCREAMING_CAPS.
Legacy declarations in SCREAMING_CAPS need not be refactored. 		 Best Practice if you have to use Constants:
private const [ConstantType] [ConstantName] = [ConstantValue]

  Best Practice if you have to use Constant Example:
private const string DataType = “StubData”;

  Not Recommended Legacy Constant Use Constant Example:
private const string DATA_TYPE = “StubData”;

These standards should be the criteria enforced during Development Code Reviews.

Legacy code should be refactored to these standards were feasible. New feature / functionality change requests will trigger refactoring to these standards whenever possible.

“The Modern Developer should always leave a Software Entity in better shape than it was in when they entered the Legacy Code environment”

– The Boy Scout Principle 

The following two tabs change content below.
Brad Huett
My Twitter profile

Brad Huett

I am a Principal Architect at Liquid Hub in the Philadelphia area specializing in Agile Practices as a Certified Scrum Master (CSM). I use Test Driven Development (TDD) and Acceptance Test Driven Development (ATDD) with Behavior Driven Development (BDD) as my bridge to Agile User Stories Acceptance Criteria in a Domain Driven Design (DDD) implementing true RESTful services
Brad Huett
My Twitter profile

Latest posts by Brad Huett (see all)

%d bloggers like this: