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


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

IdentifierCaseExample
ClassPascalBehavior
Enum typePascalMouseButton
Enum valuesCamelleftButton
EventCamelload
Exception classCamelError.argument
Static fieldCamelredValue
InterfacePascalIDisposable
Note: Always begins with the prefix I.
MethodCameltoString
NamespacePascalSys.Net
ParameterCameltypeName
PropertyCamelbackColor
Local variableCamelvar myVariable
Public instance fieldCamelhorizontal

2.3 Abbreviations

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


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


2.6.2 Interfaces


2.6.3 Enumerations

For guidance on defining enumerations, see section 4.3.6.

2.7 Type members

2.7.1 Functions


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


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


2.7.4 Events


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


Wrong: function doSomething(InputData)

Right: function doSomething(inputData)


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

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


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

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


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

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