Capitalization Conventions

Many of the naming conventions pertain to the casing of identifiers. It is important to note that the common language runtime (CLR) supports case-sensitive and case-insensitive languages. The capitalization conventions described in this topic make it easy for developers to understand and work with a library.

An acronym is a word that is formed from the letters of words in a term or phrase. For example, HTML is an acronym for Hypertext Markup Language. You should include acronyms in identifiers only when they are widely known and well understood. Acronyms differ from abbreviations in that an abbreviation shortens a single word. For example, ID is an abbreviation for identifier. In general, library names should not use abbreviations.

Note:

The two abbreviations that can be used in identifiers are ID and OK. In Pascal-cased identifiers they should appear as Id, and Ok. If used as the first word in a camel-cased identifier, they should appear as id and ok, respectively.

Casing of acronyms depends on the length of the acronym. All acronyms are at least two characters long. For the purposes of these guidelines, if an acronym is exactly two characters, it is considered a short acronym. An acronym of three or more characters is a long acronym.

The following guidelines specify the proper casing for short and long acronyms. The identifier casing rules take precedence over acronym casing rules.

Do capitalize both characters of two-character acronyms, except the first word of a camel-cased identifier.

A property named DBRate is an example of a short acronym (DB) used as the first word of a Pascal-cased identifier. A parameter named ioChannel is an example of a short acronym (IO) used as the first word of a camel-cased identifier.

Do capitalize only the first character of acronyms with three or more characters, except the first word of a camel-cased identifier.

A class named XmlWriter is an example of a long acronym used as the first word of a Pascal-cased identifier. A parameter named htmlReader is an example of a long acronym used as the first word of a camel-cased identifier.

Do not capitalize any of the characters of any acronyms, whatever their length, at the beginning of a camel-cased identifier.

A parameter named xmlStream is an example of a long acronym (xml) used as the first word of a camel-cased identifier. A parameter named dbServerName is an example of a short acronym (db) used as the first word of a camel-cased identifier.

Do not capitalize each word in so-called closed-form compound words. These are compound words written as a single word, such as "endpoint".

For example, hashtable is a closed-form compound word that should be treated as a single word and cased accordingly. In Pascal case, it is Hashtable; in camel case, it is hashtable. To determine whether a word is a closed-form compound word, check a current dictionary.

The following list identifies some common terms that are not closed-form compound words. The word is shown in Pascal casing followed by the camel-cased form in parentheses.

The capitalization guidelines exist solely to make identifiers easier to read and recognize. Casing cannot be used as a means of avoiding name collisions between library elements.

Do not assume that all programming languages are case-sensitive. They are not. Names cannot differ by case alone.

Portions Copyright 2005 Microsoft Corporation. All rights reserved.

Portions Copyright Addison-Wesley Corporation. All rights reserved.

For more information on design guidelines, see the "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" book by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley, 2005.