General Naming Conventions
This section describes general naming conventions that relate to word choice, guidelines on using abbreviations and acronyms, and recommendations on how to avoid using language-specific names.
✔️ DO choose easily readable identifier names.
For example, a property named
HorizontalAlignment is more English-readable than
✔️ DO favor readability over brevity.
The property name
CanScrollHorizontally is better than
ScrollableX (an obscure reference to the X-axis).
❌ DO NOT use underscores, hyphens, or any other nonalphanumeric characters.
❌ DO NOT use Hungarian notation.
❌ AVOID using identifiers that conflict with keywords of widely used programming languages.
According to Rule 4 of the Common Language Specification (CLS), all compliant languages must provide a mechanism that allows access to named items that use a keyword of that language as an identifier. C#, for example, uses the @ sign as an escape mechanism in this case. However, it is still a good idea to avoid common keywords because it is much more difficult to use a method with the escape sequence than one without it.
Using Abbreviations and Acronyms
❌ DO NOT use abbreviations or contractions as part of identifier names.
For example, use
GetWindow rather than
❌ DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.
Avoiding Language-Specific Names
✔️ DO use semantically interesting names rather than language-specific keywords for type names.
GetLength is a better name than
✔️ DO use a generic CLR type name, rather than a language-specific name, in the rare cases when an identifier has no semantic meaning beyond its type.
For example, a method converting to Int64 should be named
ToLong (because Int64 is a CLR name for the C#-specific alias
long). The following table presents several base data types using the CLR type names (as well as the corresponding type names for C#, Visual Basic, and C++).
✔️ DO use a common name, such as
item, rather than repeating the type name, in the rare cases when an identifier has no semantic meaning and the type of the parameter is not important.
Naming New Versions of Existing APIs
✔️ DO use a name similar to the old API when creating new versions of an existing API.
This helps to highlight the relationship between the APIs.
✔️ DO prefer adding a suffix rather than a prefix to indicate a new version of an existing API.
This will assist discovery when browsing documentation, or using IntelliSense. The old version of the API will be organized close to the new APIs, because most browsers and IntelliSense show identifiers in alphabetical order.
✔️ CONSIDER using a brand new, but meaningful identifier, instead of adding a suffix or a prefix.
✔️ DO use a numeric suffix to indicate a new version of an existing API, particularly if the existing name of the API is the only name that makes sense (i.e., if it is an industry standard) and if adding any meaningful suffix (or changing the name) is not an appropriate option.
❌ DO NOT use the "Ex" (or a similar) suffix for an identifier to distinguish it from an earlier version of the same API.
✔️ DO use the "64" suffix when introducing versions of APIs that operate on a 64-bit integer (a long integer) instead of a 32-bit integer. You only need to take this approach when the existing 32-bit API exists; don't do it for brand new APIs with only a 64-bit version.
Portions © 2005, 2009 Microsoft Corporation. All rights reserved.
Reprinted by permission of Pearson Education, Inc. from Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.