Class Naming Guidelines

When creating a class, name them with nouns or noun phrases. Also use Pascal casing (for example, CalculateInvoiceTotal) and try to use abbreviations in class names sparingly. Do not use any class prefix (such as C) since that will not add any information for the programmer—the interfaces have a prefix of I, which is enough. Do not use an underscore in the name because it takes space and seldom gives any extra information to the programmer (it does not make it easier to read, either).

An example of a class following these naming guidelines is shown here:

public class Account {
}
public class Salary {
}
public class Company {
}

Interface Naming Guidelines

When creating interfaces, we recommend you follow some common rules that give your interfaces a common look and feel, which will make it easier for others to use and maintain them.

The name of the interface should be created with nouns or noun phrases, or adjectives describing behavior—for example, IComponent (descriptive noun), ICustomAttributeProvider (noun phrase), and IPersistable (adjective). In our examples, we use Pascal casing and try to write out the complete name—abbreviations mostly make it unclear what an interface is for.

Try to avoid using underscores in the interface name, since they only take up space and seldom mean anything to the observer.

Prefix the interface names with the letter I to indicate that the type is an interface and can easily be separated from the classes in your project. However, do not prefix class names with C, which has no meaning in this case because you have a prefix for the interfaces.

When you are designing class/interface pairs, try to keep the names similar. For example, the difference should be that the interface has an I in front of the interface name, as follows:

public interface IComponent {
}
public class Component : IComponent {
}
public interface IServiceProvider{
}
public interface IFormatable {
}

Enumeration Naming Guidelines

UsePascal casing for enumerations and for their enumeration value names. Try to avoid using abbreviations in enumeration names and enumeration values and do not use a prefix/suffix on enumeration names (for example, adXXX for ADO enumerations, rtfXXX for rich text enumerations, and so on). When you construct enums, try to use singular names except for bit fields that have plural names. Try to use enums for parameters where the parameter has a defined range of possible values, as shown in the following example. This allows the development environment to know the possible values for a property or parameter.

public enum FileMode{
    Create,
    CreateNew,
    Open,
    OpenOrCreate,
    Truncate
}

If you are going to use an enum in bitwise operations, add the Flags custom attribute to the enum to enable this as follows:

[Flags]
public enum Bindings {
    CreateInstance,
    GetField,
    GetProperty,
    Static
}

An exception to this rule is when encapsulating a Win32 API—it is common to have internal definitions that come from a Win32 header. It is okay to leave these with Win32 casing, which are usually all uppercase.

Try to use Int32 as the underlying type of enum. An exception to this rule is if the enum represents flags and there are many of them (over 32), or you anticipate the enum might grow too many flags in the future, or the type needs to be different from the integer type for backward compatibility. Only use enums if the value can be completely expressed as a set of bit flags. Never use them for open sets (such as operating system version and so on).

Read-Only and Const Field Names

When you are defining constants, try to name static fields with nouns, noun phrases, or abbreviations for nouns. Use the Pascal casing as for most other types, but do not use the Hungarian type notation.

Parameter Names

Parameter names should be descriptive enough so that in most scenarios the name of the parameter and its type can be used to determine its meaning. We recommend using camel casing (for example, typeName, as shown in the following code snippet) for parameter names. Aim to name a parameter based on a parameter's meaning rather than based on the parameter's type. Programmers expect development tools to provide information about type in a handy manner, so the parameter name can be put to better use describing semantics instead of type. We therefore suggest abandoning the Hungarian type notation, which takes up some space and is difficult for everyone to strive for. (We all get tired at the end of a project and start missing the notation, don't we?) Do not use reserved parameters. If more data is needed in the next version, a new overload can be added.

Type GetType (string typeName)
string Format (string format, object [] args)

Method Naming Guidelines

Method names should be named with verbs or verb phrases using Pascal casing, as demonstrated in these examples:

RemoveAll(), GetCharArray(), Invoke()

Property Naming Guidelines

Property names should be constructed from nouns or noun phrases, again with Pascal casing. We recommend not using properties and types with the same name.

Defining a property with the same name as a type can cause some ambiguity. It is best to avoid this ambiguity, unless there is a clear justification for not doing so. For example, System.WinForms has an Icon property, and even though there is an Icon class, Form.Icon is so much easier to understand than Form.FormIcon or Form.DisplayIcon, and so on.

However, System.WinForms.UI.Control has a color property. But because there is a Color class, the Color property is named BackgroundColor, as it is a more meaningful name that does not conflict.

Following are a few examples of property names:

Text, LastIndex, Value[5]

Event Naming Guidelines

When creating event handlers, name them with the EventHandler suffix as follows:

Public delegate void MouseEventHandler (object sender, MouseEvent e);

The event handler should have two parameters, sender and e. The sender parameter represents the object that raised the event. The sender parameter is always of type object, even if it is possible to employ a more specific type. The state associated with the event is encapsulated in an instance of an event class named e. Use an appropriate and specific event class for its type.

public delegate void MouseEventHandler(object sender, MouseEvent e);

Classes that handle events should be named with the EventArgs suffix as follows:

public class MouseEventArgs : EventArgs {
    int x, y;
    public MouseEventArgs(int x, int y)
        { this.x = x; this.y = y; }
    public int X { get { return x; } }
    public int Y { get { return y; } }
}

Event names that have a concept of pre- and post-operation should be prefixed using the present and past tense (do not use the BeforeXxx\AfterXxx pattern). For example, a Close event of a file that could be canceled would have events named Closing and Closed.

public event ControlEventHandler Closing {
 //..
}

Always try to name events with a verb.

Variables Naming Guidelines

Naming of variables in an enterprise application is important. It is much easier to maintain an application with variable names that describe the use of those variables than with an application that has single-character variables that do not give any clues to the programmer how those variables are used.

The following variable naming guidelines is an extract of the complete guidelines that can be found at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vsent7/html/vxconcodingtechniques.asp:

• Since most names are constructed by concatenating several words, use mixed-case formatting to simplify reading them. In addition, to help distinguish between variables and routines, use Pascal casing (CalculateInvoiceTotal), in which the first letter of each word is capitalized, for routine names. For variable names, use camel casing (documentFormatType), in which the first letter of each word except the first is capitalized.

• Boolean variable names should contain Is, which implies yes/no or true/false values, such as fileIsFound.

• Avoid using terms such as Flag when naming status variables, which differ from Boolean variables in that they may have more than two possible values. Instead of documentFlag, use a more descriptive name such as documentFormatType.

• Even for a short-lived variable that may appear in only a few lines of code, you should still use a meaningful name. Use single-letter variable names, such as i, or j, for short-loop indexes only.

• The Hungarian naming convention prefix all variables with their scope and their data type. An example is: dim g_blnIsDeleted as Boolean where the g stands for global scope of the variable, the bln for Boolean.

Structured Exception Handling

Use the try-catch-finally statement in C# to do the following:

• Handle situations involving a function that cannot fulfill its contract.

• Catch expected error conditions—but do not rely on exceptions. What we mean is that you should validate the data with code, not validate it by catching an error that occurs because of invalid data.

• Ensure cleanup after unexpected exception conditions.

Error Raising and Handling

Following are some useful conventions for error raising and handling:

• Do end Exception class names with Exception to separate them from normal classes.

  public class FileNotFoundException : Exception {
  }
  

• Use at least these common constructors for your own exception classes:

  public class XxxException : Exception {
      XxxException() { }
      XxxException(string message) { }
      XxxException(string message, Exception inner) { }
  }
  

• We recommend using the predefined exception types. Only define new exception types for programmatic scenarios. Introduce a new exception class so a programmer can take a different action in code based on the exception class. Do not define a new exception class unless it is possible a developer might need the exception class.

  For example, it makes sense to define FileNotFoundException because the programmer might decide to create the missing file, whereas FileIOException is not something that would typically be handled specifically in code.

• In exceptions that do not have an explicit message, make sure the message property traverses down the tree to the next real text.

• Do not derive new exceptions from the base class Exception. The base class will have multiple subclasses according to the individual namespace.

• Remember that under the system exception will be another container exception called Core, which will contain the handful of EE exceptions that bring the system down completely. Users cannot throw these exceptions.

• Group new exceptions off the base class Exception by namespace. For example, subclasses will exist for XML, IO, Collections, and so on; each of these areas subclass their own exceptions as appropriate. Any exceptions that other library or application writers wish to add will extend the Exception base class directly. A single name for all related exceptions should be made, and all exceptions related to that application or library should extend from that bucket.

• Use a localized description string. An error message displayed to the user will be derived from the description string of the exception that was thrown, and never from the exception class. Include a description string in every exception to clarify for the end user what happened.

• Use grammatically correct error messages including ending punctuation. Each sentence in a description string of an exception ends in a period. Code that generically displays an exception message to the user handles the case when a developer forgets the final period.

• Provide Exception properties for programmatic access. Include extra information in an exception (besides the description string) only when there exists a programmatic scenario in which that additional information would be useful. It is rare to need to include additional information in an exception.

• Throw exceptions only in exceptional cases:

• Do not use exceptions for normal or expected errors.

• Do not use exceptions for normal flow of control, as there is an overhead for generating exceptions instead of checking that you have valid values.

• Return null for extremely common error cases. For example, File.Open returns a null if the file is not found, but throws an exception if the file is locked.

• Design classes so that in the normal course of use there will never be an exception thrown. For example, a FileStream class exposes another way of determining if the end of file has been reached to avoid the exception that will be thrown if the developer reads past the end of the file. For example:

  class Foo {
      void Bar() {
          FileStream stream = File.Open("mytextfile.txt");
          byte b;
           // ReadByte returns -1 at EOF
          while ((b = stream.ReadByte()) > = 0) {
              // Do something
          }
      }
  }
  

• Throw an InvalidOperationException if in an inappropriate state. The System.InvalidOperationException exception is supposed to be thrown if the property set or method call is not appropriate given the object's current state.

• Throw an ArgumentException or subclass thereof if bad parameters are passed. When bad parameters are detected, throw a System.ArgumentException or a subclass thereof.

• Do realize that the stack trace starts at the throw. The stack trace's origin is located where the exception is thrown, not where it is reviewed. Be aware of this fact when deciding where to throw an exception.

• Use exception builder methods. It is common for a class to throw the same exception from different places in its implementation. To avoid code bloat, use a helper method that creates a new exception and return it. For example:

  class File {
      string fileName;
  
      public byte[] Read(int bytes) {
          if (!ReadFile(handle, bytes))
              throw NewFileIOException();
      }
        FileException NewFileIOException() {
       string description = // Build localized string,
  //including fileName
           return new FileException(description);
       }
  }
  

  Another alternative is to use the constructor of the exception to build the exception. This is more appropriate for global exception classes like ArgumentException.

• Throw exceptions in favor of returning an error code (or HResult).

• Throw the most specific exception possible.

• Use existing exceptions where possible instead of creating new ones.

• Set all the fields on the exception you use.

• Use inner exceptions (chained exceptions).

• Create meaningful message text targeted at the developer in the exception.

• Do not include methods that throw NullReferenceException or IndexOutOfRangeException.

• Do argument checking on protected (family) members. Write clearly in the documentation if the protected method does not do argument checking. Unless otherwise stated, assume argument checking is done. You may get some performance gains in not doing argument checking.

• Clean up intermediate results when throwing an exception. Callers should be able to assume that there are no side effects when an exception is thrown from a function.

  For example, if Hashtable.Insert throws an exception, then the caller can assume that the item was not added to the hash table (the hash table implementation breaks this rule, but that's another issue).

Pass All Data Back to the Client in a Method Call

In general, stateless objects produce highly scalable solutions. The data access classes are stateless; that is, they do not keep state in instance data members. The client passes all data required for a particular action to a method, and the method passes all resulting data back to the client.

This approach simplifies resource management by freeing every data access object following any method call. As a result, the client can use any data access object to make a method call, because all the required inputs are passed to the object with the call.

As a consequence, you need to keep transaction lifetime longer than any of the connections to the database. The standard transactional support in Component Services (COM+) that uses the Distributed Transaction Coordinator (DTC) will be employed to accomplish this (see the section "Transaction Strategy"). By using the JIT and the object pooling support found in COM+, you can reduce the overhead to create new objects for each call.

Hold Database Resources for a Minimum Length of Time

Database resources are limited and expensive. The data access layer postpones database resource allocation as long as possible and frees database resources as soon possible. The data access classes implement Finalize/Dispose semantics to close the active database connection. The data access objects are allocated and released at the point of a database call in the scope of either a using or try-finally block.

Transaction Strategy

Transactions are initiated in the business layer using the transactional support in COM+. Often, nested local transactions yield better performance than distributed transactions executed by serviced components running under control of the Distributed Transaction Coordinator (DTC). However, that performance is marginal compared to the increased complexity of the implementation, so use the support for transactions found in COM+.