Naming and Coding Conventions
Coding conventions can be unpopular, particularly where they are imposed on a team by a non-programmer and contain dated or restrictive rules. Every programmer has their own opinion about the usefulness of naming guidelines, coding conventions, and other code-related rules. The opinions range from those who think that any coding convention ruins the programmer's creative style, to those who thrive on the structure that conventions and standards provide.
Once again, we're faced with finding a compromise that benefits everybody. Standardization not only allows teams of programmers to produce code that follows the same conventions, making it easier to read and maintain, but it allows for the same programmer to write consistent code. Far more often than we like to admit, programmers will use one convention one day, and another convention the next. Without some sense of enforced structure to the programming, the infamous spaghetti code will rear its ugly head and make life miserable for everyone involved. Another common practice that ensures solid, standardized code is the use of code reviews. Code reviews are where other programmers (or managers, depending on skill distribution) review their peers' code for accuracy, efficiency, and compliance to coding standards and conventions. Some programmers resist this kind of practice, but it can be extremely valuable and productive.
The guidelines here tend to match the recommendations that Microsoft issues to its own .NET development teams. If we haven't pointed out a difference between our standards and Microsoft's, then they're essentially the same. When in doubt, it is generally a good idea to favor established methods that developers are already familiar with. Change can often bring with it benefits; but it can also be something that programmers resist strongly.
Naming Guidelines
Naming guidelines actually cover two things: naming and casing. The following is a list of generic guidelines that apply to both naming and casing. Microsoft strongly recommends the use of a capitalization scheme called Pascal casing. Pascal casing is a scheme where all words in an identifier have the first letter capitalized and there is no separation character between words. Another type of capitalization scheme is called camel casing. This is where the first letter of the identifier is lowercased, and thereafter the first letter of each word is capitalized. The following table is a summary of Microsoft's capitalization suggestions:
Type
|
Case
|
Additional Information
|
Class
|
PascalCase
|
Examples: MyClass, Utility, DataHelper
|
Enum value
|
PascalCase
|
Examples: Colors.Red, PossibleValues.ValueOff
|
Enum type
|
PascalCase
|
Examples: Colors, PossibleValues
|
Event
|
PascalCase
|
Examples: MouseClick, ButtonDown
|
Exception class
|
PascalCase
|
Class name ends with Exception suffix, for example: MyCustomException, WebServiceException
|
Interface
|
PascalCase
|
Interface name is prefixed with the letter I, for example: ICar, ISerializable
|
Method
|
PascalCase
|
Examples: GetItemData, UpdateModifiedValue
|
Namespace
|
PascalCase
|
Examples: Company.NewApplication.DataTier
|
Property
|
PascalCase
|
Examples: ItemValue
|
Parameter
|
camelCase
|
Examples: itemArray, valueData, purchasePrice
|
Private member variable
|
camelCase
|
Microsoft makes no recommendation on this; however, it is useful to distinguish private member variables from other identifiers.
|
In addition to the above summary of capitalization rules, the following guidelines apply to naming classes, interfaces, and namespaces:
Do not use class names that overlap with namespaces, especially those namespaces that are supplied by Microsoft. So stay away from naming your classes things like System, UI, Collections, or Forms.
Do not use the underscore character. Many of us who have been writing C++ code for a long time have developed the habit of using a preceding underscore to indicate a private member variable within a class. This practice has fallen from grace, and is now discouraged.
Do not use identifier names that conflict with keywords. Most languages won't let you anyway!
Do not use abbreviations in your identifiers. Also, where you use an acronym, treat it as a word - don't use all uppercase. For example, the .NET Framework has namespaces such as SqlClient (not SQLClient).
Do follow the casing conventions in brand names. For example, if you place your company name in a namespace, and your company name has a specifically branded capitalization scheme (for example NeXT or IBM, both of which have a capitalization scheme that doesn't coincide with the casing recommendations) you should retain your company's branding. So, you would not reduce IBM in a namespace to Ibm, nor would you reduce NeXT in a namespace to Next.
Do use nouns and noun phrases when naming your classes and namespaces. This is highly recommended and preferred over using verbs. For example, use Parser as a namespace or class name, rather than Parse or Parsing. Verbs should be used for method names only.
Do not use Hungarian notation when naming things. For example, in classic VB, controls were often given names like btnConfirm, which would immediately tell the reader that it was a button. Microsoft's style guidelines are now recommending that people do not prefix their variable names with anything related to that variable's data type. Microsoft feels that the development tools (specifically VS .NET) should provide information pertaining to a given member's data type by such means as intelligent hovering pop-up dialogs. A better purpose for a variable name is to describe its use rather than its data type. Interestingly enough, Microsoft does recommend the usage of Hungarian notation prefixes on static member names.
There are a lot of code conventions to remember, and for some people it is a radical switch in development style. The important thing is to have guidelines, even if they are different from those given here. If two programmers agree to follow guidelines, then there is a very good chance that they will produce code that looks similar and is just as easy to read. You can find all the information you need on Microsoft's recommended design, naming, and coding convention guidelines in the MSDN documentation that comes with the .NET Framework SDK. Some topic names to look up include:
Parameter naming guidelines
Property naming guidelines
Event usage guidelines
Method usage guidelines
Field usage guidelines
Static field naming guidelines
It's a good idea to follow the Microsoft guidelines wherever possible. Microsoft code samples all follow these guidelines, including those in the .NET documentation. Writing code using this style will make it easier to read other code in that style.