Naming Standards

Modified on 2010/05/06 18:55 by Stephen Walther — Categorized as: Uncategorized

This section presents standards for naming JavaScript language elements. Naming consistency is an essential first step to improving the clarity, readability, and therefore maintainability of code when many developers are working on it.

The standards in this section have been adapted to JavaScript from those defined for other languages, in particular those that have well established and proven naming standards. The adaptation process has considered and prioritized JavaScript compatibility and performance.

2.1 Capitalization Styles

2.1.1 Pascal case

The first letter in the identifier and the first letter of each subsequent concatenated word are capitalized. You can use Pascal case for identifiers of three or more characters. For example:

BackColor

2.1.2 Camel case

The first letter of an identifier is lowercase and the first letter of each subsequent concatenated word is capitalized. For example:

backColor

2.1.3 Uppercase

All letters in the identifier are capitalized. Use this convention only for identifiers that consist of two or fewer letters. For example:

Wrong: Io

Right: IO

Wrong: TCP

Right: Tcp

2.1.4 Hungarian Notation

The identifier is preceded by text that indicates the data type it represents. For example, a string variable may be named strValue, and an integer intValue.

This approach is not recommended for any JavaScript language element.

2.2 Capitalization and Case Sensitivity

Do not create two namespaces with names that differ only by case.
Do not create a namespace with type names that differ only by case.
Do not create a function with parameter names that differ only by case.
Do not create a type with property, method, field or event names that differ only by case.

The following table summarizes the capitalization rules and provides examples for the different types of identifiers.

Identifier	Case	Example
Class	Pascal	`Behavior`
Enum type	Pascal	`MouseButton`
Enum values	Camel	`leftButton`
Event	Camel	`load`
Exception class	Camel	`Error.argument`
Static field	Camel	`redValue`
Interface	Pascal	`IDisposable` Note: Always begins with the prefix I.
Method	Camel	`toString`
Namespace	Pascal	`Sys.Net`
Parameter	Camel	`typeName`
Property	Camel	`backColor`
Local variable	Camel	`var myVariable`
Public instance field	Camel	`horizontal`

2.3 Abbreviations

To avoid confusion follow these rules regarding the use of abbreviations:

Do not use abbreviations or contractions as parts of identifier names. For example, use getWindow instead of getWin.
Do not use acronyms that are not generally accepted in the computing field or your particular business context.
Where appropriate, use well-known acronyms to replace lengthy phrase names. For example, use UI for User Interface and Olap for On-line Analytical Processing.
When using acronyms, use Pascal case or camel case for acronyms more than two characters long. For example, use HtmlButton or htmlButton. However, you should capitalize acronyms that consist of only two characters, such as Sys.UI instead of Sys.Ui. Do not use abbreviations in identifiers or parameter names. If you must use abbreviations, use camel case for abbreviations that consist of more than two characters, even if this contradicts the standard abbreviation of the word.

2.4 Conventions

2.4.1 Type visibility

JavaScript has no concept of public or private members other than that determined as a result of variable scope. Therefore, when writing Object Oriented JavaScript, prefix members that are intended to be private with an underscore (“_”). For example, in Sys.EventHandlerList, a private member named “_list” is declared:

Sys.EventHandlerList = function EventHandlerList() {
    this._list = {};
}

Visual Studio also excludes members prefixed with an underscore from Intellisense.

2.4.2 Uniqueness

Avoid using the same name for multiple type members, such as events and properties. Ensure each is unique to maintain clarity of code.

2.5 Namespaces

The general rule for naming namespaces is to use the company name followed by the technology name. This is to avoid the possibility of two published namespaces having the same name. CompanyName.TechnologyName.Feature

For example:


Microsoft.Media 
Microsoft.Office.Word

Use a stable, recognized technology name at the second level of a hierarchical name. Use organizational hierarchies as the basis for namespace hierarchies. A nested namespace should have a dependency on types in the containing namespace. For example, the classes in the Sys.UI depend on the classes in Sys. However, the classes in Sys do not depend on the classes in Sys.UI.

You should use Pascal case for namespaces, and separate logical components with periods, as in Microsoft.Office.PowerPoint. If your brand employs non-traditional casing, follow the casing defined by your brand, even if it deviates from the prescribed Pascal case. For example, the fictional namespaces Microsoft.newProducteXample and contoso.secureIT illustrate appropriate deviations from the Pascal case rule.

Use plural namespace names if it is semantically appropriate. For example, use Sys.Collections rather than Sys.Collection. Exceptions to this rule are brand names and abbreviations.

Do not use the same name for a namespace and a class. For example, do not provide both a Debug namespace and a Debug class. Namespaces are referred to regularly in script and therefore should be kept appropriately brief to minimize download size whilst still being descriptive. For example, the Ajax Control Toolkit uses Sys instead of System. Similarly, avoid nesting namespaces too deep to keep them succinct, such as Sys.UI rather than Sys.UI.Controls.

Finally, see section 3.7.2 for guidance on naming JavaScript files.

2.6 Type naming

2.6.1 Classes

Use a noun or noun phrase to name a class.
Use Pascal case.
Use abbreviations sparingly.
Do not use a type prefix, such as C for class, on a class name. For example, use the class name Dialog rather than CDialog.
Do not use the underscore or dollar characters (_ and $).
Occasionally, it is necessary to provide a class name that begins with the letter I, even though the class is not an interface. This is appropriate as long as I is the first letter of an entire word that is a part of the class name. For example, the class name IdentityStore is appropriate, as is the interface name IIdentityStore.
Where appropriate, use a compound word to name a derived class. The second part of the derived class's name should be the name of the base class. For example, ArgumentException is an appropriate name for a class derived from a class named Exception, because ArgumentException is a kind of Exception. Use reasonable judgment in applying this rule. For example, CustomButton is an appropriate name for a class derived from Control. Although a customized button is a kind of control, making Control a part of the class name would lengthen the name unnecessarily.

2.6.2 Interfaces

Name interfaces with nouns or noun phrases, or adjectives that describe behavior. For example, the interface name IContainer uses a descriptive noun. The interface name ICustomAttributeProvider uses a noun phrase. The name IDisposable uses an adjective.
Use Pascal case.
Use abbreviations sparingly.
Prefix interface names with the letter I, to indicate that the type is an interface.
Use similar names when you define a class/interface pair where the class is a standard implementation of the interface. The names should differ only by the letter I prefix on the interface name.
Do not use the underscore or the dollar character (_ and $).

2.6.3 Enumerations

For guidance on defining enumerations, see section 4.3.6.

Use Pascal case for Enum types and camel case for value names.
Use abbreviations sparingly.
Do not use an Enum suffix on Enum type names.
Use a singular name for Enum types.

2.7 Type members

2.7.1 Functions

Use verbs or verb phrases to name methods.
Use camel case for method names.

Use an underscore (“_”) prefix for methods that are intended to be private (see 2.4.1). To ensure that JavaScript debuggers and profilers can correctly infer a type member’s name, avoid anonymous functions in debug scripts. For example:

Wrong: Sys.toString = function () { ... code ...}

Right: Sys.toString = function toString() { ... code ...}

Release versions of these scripts usually omit function names to reduce the size of the download.

For information on ensuring that these function names are kept unique and do not clash with other scripts see section 3.7.1.

2.7.2 Properties

Use a noun or noun phrase to name properties.
Use camel case (get_myProperty, set_myProperty).
Do not use Hungarian notation (see section 2.1.4).
If possible create a property with the same name as its underlying type. For example, if you declare a property named "color", the type of the property should likewise be Color.

Property accessors should always be prefixed with “get_” and “set_” respectively. For example:

    MyApp.Person.get_name = 
        function get_name() { return _name; }

2.7.3 Fields

Use nouns, noun phrases, or abbreviations of nouns to name static fields.
Use camel case.
Do not use a Hungarian notation prefix on static field names.
Use an underscore (“_”) prefix for fields that are intended to be private (see 2.4.1)
this._name = '';

2.7.4 Events

Use camel case (add_myEvent, remove_myEvent).
Do not use Hungarian notation.
Specify two parameters named sender and args. The sender parameter represents the object that raised the event. The state associated with the event is encapsulated in an instance of an event class named args. Use an appropriate and specific event class for the args parameter type.
Name an event argument class with the EventArgs suffix.
Consider naming events with a verb. For example, correctly named event names include clicked, painting, and droppedDown.
Use a gerund (the "ing" form of a verb) to create an event name that expresses the concept of pre-event, and a past-tense verb to represent post-event. For example, a close event that can be canceled should have a closing event and a closed event. Do not use the beforeXxx/afterXxx naming pattern.
Do not use a prefix or suffix on the event declaration on the type. For example, use close instead of onClose.

Event accessors should always be prefixed with “add_” and “remove_” respectively. For example:

    function add_click() { ... code ...}
    function remove_click() { ... code ...}

For further information on defining events see section 4.4.7.

2.8 Parameters

Use camel case for parameter names.

Wrong: function doSomething(InputData)

Right: function doSomething(inputData)

Use descriptive parameter names in Debug script versions. Release scripts may use abbreviated names. Parameter names should be descriptive enough that the name of the parameter and its type can be used to determine its meaning in most scenarios. For example, visual design tools that provide context sensitive help display method parameters to the developer as they type. The parameter names should be descriptive enough in this scenario to allow the developer to supply the correct parameters.

Wrong: function copy(a, b) { ... code ...}

Right: function copy(source, destination) { ... code ...}

Use names that describe a parameter's meaning rather than names that describe a parameter's type. Development tools should provide meaningful information about a parameter‘s type if Documentation Comments are used (see section 3.4.1). Therefore, a parameter's name can be put to better use by describing meaning.

Wrong: function doSomething(str, integer) { ... code ...}

Right: function doSomething(message, length) { ... code ...}

Do not prefix parameter names with Hungarian type notation (see section 2.1.4).

Wrong: function doSomething(strMessage, intLength) { ... code ...}

Right: function doSomething(message, length) { ... code ...}