Naming

Two naming conventions are used.

• PascalCasing capitalizes the first character of each word.
• camelCasing is the same as PascalCasing, except the first character of the first word isn’t capitalized.

In general, PascalCasing is used for anything that would be visible externally from a class, such as classes, enums, methods, and so on. The exception to this is method parameters, which are defined using camelCasing.

Private members of classes, such as fields, are defined using camelCasing.

There are a few other conventions in naming.

• Avoid common keywords in naming to decrease the chance of collisions in other languages.
• Event classes should end with EventArgs.
• Exception classes should end with Exception.
• Interfaces should start with I.
• Attribute classes should end in Attribute.

Hungarian naming (prefixing the name of the variable with the type of the variable) is discouraged for C# code because the added information about the variable isn’t as important as making the code easier to read. For example, strEmployeeName is tougher to read than employeeName.¹

Conventions such as adding m_ or _ at the beginning of fields to denote that the field belongs to an instance is a matter of personal choice.

Class Naming

To help prevent collisions between namespaces and classes provided by different companies, namespaces should be named using the CompanyName.TechnologyName convention. For example, the full name of a class to control an X-ray laser would be something like this:

AppliedEnergy.XRayLaser.Controller

Compiler Support Tags

The compiler support tags are a good example of compiler magic; they are processed using information that is known only to the compiler. The following example illustrates the use of the support tags:

// file: employee.cs
using System;
namespace Payroll
{
    /// <summary>
    /// The Employee class holds data about an employee.
    /// This class class contains a <see cref="String">string</see>
    /// </summary>
    public class Employee
    {
       /// <summary>
       /// Constructor for an Employee instance. Note that
       /// <paramref name="name">name2</paramref> is a string.
       /// </summary>
       /// <param name="id">Employee id number</param>
       /// <param name="name">Employee Name</param>
       public Employee(int id, string name)
       {
            m_id = id;
            m_name = name;
       }
       /// <summary>
       /// Parameterless constructor for an employee instance
       /// </summary>
       /// <remarks>
       /// <seealso cref="Employee(int, string)">Employee(int, string)</seealso>
       /// </remarks>
       public Employee()
       {
            m_id = −1;
            m_name = null;
       }
       int m_id;
       string m_name;
    }
}

The compiler performs special processing on four of the documentation tags. For the param and paramref tags, it validates that the name referred to inside the tag is the name of a parameter to the function.

For the see and seealso tags, it takes the name passed in the cref attribute and looks it up using the identifier lookup rules so that the name can be resolved to a fully qualified name. It then places a code at the front of the name to tell what the name refers to. For example, the following:

<see cref="String">

becomes the following:

<see cref="T:System.String">

String resolved to the System.String class, and T: means that it’s a type.

The seealso tag is handled in a similar manner. The following:

<seealso cref="Employee(int, string)">

becomes the following:

<seealso cref="M:Payroll.Employee.#ctor(System.Int32,System.String)">

The reference was to a constructor method that had an int as the first parameter and a string as the second parameter.

In addition to the preceding translations, the compiler wraps the XML information about each code element in a member tag that specifies the name of the member using the same encoding. This allows a postprocessing tool to easily match up members and references to members.

The generated XML file from the preceding example is as follows (with a few word wraps):

<?xml version="1.0"?>
<doc>
    <assembly>
       <name>employee</name>
    </assembly>
    <members>
       <member name="T:Payroll.Employee">
            <summary>
            The Employee class holds data about an employee.
            This class class contains a <see cref="T:System.String">string</see>
            </summary>
       </member>
       <member name="M:Payroll.Employee.#ctor(System.Int32,System.String)">
            <summary>
            Constructor for an Employee instance. Note that
            <paramref name="name2">name</paramref> is a string.
            </summary>
            <param name="id">Employee id number</param>
            <param name="name">Employee Name</param>
       </member>
       <member name="M:Payroll.Employee.#ctor">
            <summary>
            Parameterless constructor for an employee instance
            </summary>
            <remarks>
            <seealso cref="M:Payroll.Employee.#ctor(System.Int32,System.String)"
>Employee(int, string)</seealso>
            </remarks>
       </member>
    </members>
</doc>

Generating Real Documentation

The best way to generate documentation from the XML output of the compiler is by using SandCastle,² a free tool supported by Microsoft. It can generate documentation that looks like the MSDN documentation.

XML Documentation Tags

The remaining XML documentation tags describe the .NET documentation conventions. The tags are listed in Table 39-2.

The compiler does not enforce a specific schema on the XML tags that are used in the XML comments; it requires only that the XML be well-formed. This allows it to be extended at will; a team could add an 272103_1_En tag or a <version> tag if desired, and it will be passed into the resulting XML file.

XML Include Files

In a project that has a separate technical-writing team, it may be more convenient to keep the XML text outside of the code. To support this, C# provides an include syntax for XML documentation. Instead of having all the documentation before a function, the following include statement can be used:

/// <include file='Foo.csx' path='doc/member[@name="Foo.Comp"]' />

This will open the Foo.csx file and look for a <doc> tag. Inside the doc section, it will then look for a <member> tag that has the name Foo.Comp specified as an attribute. Here’s an example:

<doc>
    <member name="Foo.Comp">
       <summary>A description of the routine</summary>
       <param name="obj1">the first object</param>
    </member>
    . . .
</doc>

Once the compiler has identified the matching section from the include file, it proceeds as if the XML were contained in the source file.

Allocation

Heap allocation in the .NET Runtime world is very fast; all the system has to do is make sure that there’s enough room in the managed heap for the requested object, return a pointer to that memory, and increment the pointer to the end of the object.

Garbage collectors trade simplicity at allocation time for complexity at cleanup time. Allocations are really, really fast in most cases, though if there isn’t enough room, a garbage collection might be required to obtain enough room for object allocation.

Of course, to make sure that there’s enough room, the system might have to perform a garbage collection.

To improve performance, large objects (greater than 85KB in size, though this number is subject to change) are allocated from a large object heap.

Mark and Compact

The .NET garbage collector uses a “Mark and Compact” algorithm. When a collection is performed, the garbage collector starts at root objects (including globals, statics, locals, and CPU registers) and finds all the objects that are referenced from those root objects. This collection of objects denotes the objects that are in use at the time of the collection, and therefore all other objects in the system are no longer needed.

To finish the collection process, all the referenced objects are copied down in the managed heap, and the pointers to those objects are all fixed up. Then, the pointer for the next available spot is moved to the end of the referenced objects.

Since the garbage collector is moving objects and object references, there can’t be any other operations going on in the system. In other words, all useful work must be stopped while the GC takes place.

Generations

It’s costly to walk through all the objects that are currently referenced. Much of the work in doing this will be wasted work, since the older an object is, the more likely it is to stay around. Conversely, the younger an object is, the more likely it is to be unreferenced.

The runtime capitalizes on this behavior by implementing generations in the garbage collector. It divides the objects in the heap into three generations.

Generation 0 objects are newly allocated objects that have never been considered for collection. Generation 1 objects have survived a single garbage collection, and generation 2 objects have survived multiple garbage collections. In design terms, generation 2 tends to contain long-lived objects such as applications, generation 1 tends to contain objects with medium lifetimes such as forms or lists, and generation 0 tends to contain short-lived objects such as local variables.

When the runtime needs to perform a collection, it first performs a generation 0 collection. This generation contains the largest percentage of unreferenced objects and will therefore yield the most memory for the least work. If collecting that generation doesn’t generate enough memory, generation 1 will then be collected and finally, if required, generation 2.

Figure 39-1 illustrates some objects allocated on the heap before a garbage collection takes place. The numerical suffix indicates the generation of the object; initially, all objects will be of generation 0. Active objects are the only ones shown on the heap, but there is space for additional objects to be allocated.

At the time of the first garbage collection, B and D are the only objects that are still in use. The heap looks like Figure 39-2 after collection.

Since B and D survived a collection, their generation is incremented to 1. New objects are then allocated, as shown in Figure 39-3.

Time passes. When another garbage collection occurs, D, G, and H are the live objects. The garbage collector tries a generation 0 collection, which leads to the layout shown in Figure 39-4.

Even though B is no longer live, it doesn’t get collected because the collection was only for generation 0. After a few new objects are allocated, the heap looks like Figure 39-5.

Time passes, and the live objects are D, G, and L. The next garbage collection does both generation 0 and generation 1 and leads to the layout shown in Figure 39-6.

Finalization

The garbage collector supports a concept known as finalization, which is somewhat analogous to destructors in C++. In the C# spec, they are known as destructors and are declared with the same syntax as C++ destructors (with the ∼ClassName syntax), but from the runtime perspective, they are known as finalizers,³ and that is the name that I will use.

Finalizers allow the opportunity to perform some cleanup before an object is garbage collected. They are useful in cases where the class owns a resource that the garbage collector doesn’t know something about; perhaps it created an unmanaged resource to perform interop.

When an object with a finalizer is allocated, the runtime adds the object reference to a list of objects that will need finalization. When a garbage collection occurs, if an object has no references but is contained on the finalization list, it is marked as ready for finalization.

After the garbage collection has completed, the finalizer thread wakes up and calls the finalizer for all objects that are ready for finalization. After the finalizer is called for an object, it is removed from the list of objects that need finalizers, which will make it available for collection the next time garbage collection occurs.

This scheme results in the following limitations regarding finalizers:

• Objects that have finalizers have more overhead in the system, and they hang around longer; an object that could be collected has to wait until the next collection. This also means that the object is promoted to the next generation, so you have to wait that much longer for the object to be collected.
• Finalization takes place on a separate thread from execution, which makes the timing of collection unspecified.
• There is no guaranteed order for finalization. If object a has a reference to object b and both objects have finalizers, the object b finalizer might run before the object a finalizer, and therefore object a might not have a valid object b to use during finalization.
• While finalizers are usually called on normal program exit, there are times where this will not occur. If a process is terminated aggressively (for example, if the Win32 TerminateProcess function is called), finalizers will not run. Finalizers can also fail to run if the finalization queue gets stuck running finalizers for a long time on process exit. In this case, attempts to run the finalizers will time out.

Finalizers should be used only in the following situations:

• A class holds an unmanaged resource and needs to dispose of it when an instance of the class is no longer being used. If at all possible, the class should use a SafeHandle instance to hold the unmanaged resource instead of creating a finalizer. If the class does declare a finalizer, it should also implement the Dispose() pattern.
• A singleton class needs to perform a shutdown operation.
• While a program is under development, a finalizer can identify cases where Dispose() is not being called.

Controlling GC Behavior

At times, it may be useful to control the GC behavior. This should be done in moderation; the whole point of a managed environment is that it controls what’s going on, and controlling it tightly can lead to problems elsewhere.

Listing All the Types in an Assembly

This example looks through an assembly and locates all the types in that assembly.

using System;
using System.Reflection;
enum MyEnum
{
    Val1,
    Val2,
    Val3
}
class MyClass
{
}
struct MyStruct
{
}
class Test
{
    public static void Main(String[] args)
    {
            // list all types in the assembly that is passed
            // in as a parameter
       Assembly assembly = Assembly.LoadFrom (args[0]);
       Type[] types = assembly.GetTypes();
            // look through each type, and write out some information
            // about them.
       foreach (Type type in types)
       {
            Console.WriteLine ("Name: {0}", type .FullName);
            Console.WriteLine ("Namespace: {0}", type .Namespace);
            Console.WriteLine ("Base Class: {0}", type .BaseType.FullName);
       }
    }
}

If this example is run, passing the name of the .exe in, it will generate the following output:

Name: MyEnum
Namespace:
Base Class: System.Enum
Name: MyClass
Namespace:
Base Class: System.Object
Name: MyStruct
Namespace:
Base Class: System.ValueType
Name: Test
Namespace:
Base Class: System.Object

Finding Members

This example will list the members of a type.

using System;
using System.Reflection;
class MyClass
{
    MyClass() {}
    static void Process()
    {
    }
    public int DoThatThing(int i, Decimal d, string[] args)
    {
       return(55);
    }
    public int m_value = 0;
    public float m_log = 1.0f;
    public static int m_value2 = 44;
}
class Test
{
    public static void Main(String[] args)
    {
            // Iterate through the fields of the class
       Console.WriteLine("Fields of MyClass");
       Type type = typeof (MyClass);
       foreach (MemberInfo member in type.GetFields())
       {
            Console.WriteLine("{0}", member);
       }
            // and iterate through the methods of the class
       Console.WriteLine("Methods of MyClass");
       foreach (MethodInfo method in type.GetMethods())
       {
            Console.WriteLine("{0}", method);
            foreach (ParameterInfo parameter in method.GetParameters())
            {
                Console.WriteLine(" Param: {0} {1}",
                   parameter.ParameterType, parameter.Name);
            }
       }
    }
}

This example produces the following output:

Fields of MyClass
Int32 value
Single log
Int32 value2
Methods of MyClass
Void Finalize ()
Int32 GetHashCode ()
Boolean Equals (System.Object)
  Param: System.Object obj
System.String ToString ()
Void Process ()
Int32 DoThatThing (Int32, System.Decimal, System.String[])
  Param: Int32 i
  Param: System.Decimal d
  Param: System.String[] args
System.Type GetType ()
System.Object MemberwiseClone ()

For information on how to reflect over an enum, see Chapter 21.

When iterating over the methods in MyClass, the standard methods from object also show up.

Invoking Functions

In this example, reflection will be used to open the names of all the assemblies on the command lines, to search for the classes in them that implement a specific interface, and then to create an instance of those classes and invoke a function on the instance.

This is useful to provide a very late-bound architecture, where a component can be integrated with other components’ runtime.

This example consists of four files. The first one defines the IProcess interface that will be searched for. The second and third files contain classes that implement this interface, and each is compiled to a separate assembly. The last file is the driver file; it opens the assemblies passed on the command line and searches for classes that implement IProcess. When it finds one, it instantiates an instance of the class and calls the Process() function.

File IProcess.cs
namespace MamaSoft
{
    interface IProcess // the interface we will search for.
    {
       string Process(int param);
    }
}

File Process1.cs
using System;
namespace MamaSoft
{
    class Processor1: IProcess
    {
       public Processor1() {}
       public string Process(int param)
       {
            Console.WriteLine("In Processor1.Process(): {0}", param);
            return("Raise the mainsail! ");
       }
    }
}

File Process2.cs
using System;
namespace MamaSoft
{
    class Processor2: IProcess
    {
       public Processor2() {}
       public string Process(int param)
       {
            Console.WriteLine("In Processor2.Process(): {0}", param);
            return("Shiver me timbers! ");
       }
    }
}
class Unrelated
{
}

File Driver.cs
using System;
using System.Reflection;
using MamaSoft;
class Test
{
    public static void ProcessAssembly(string aName)
    {
       Console.WriteLine("Loading: {0}", aName);
       Assembly assembly = Assembly.LoadFrom (aName);
            // walk through each type in the assembly
       foreach (Type type in assembly .GetTypes())
       {
                // if it's a class, it might be one that we want.
            if (type.IsClass)
            {
                Console.WriteLine(" Found Class: {0}", type.FullName);
                   // check to see if it implements IProcess
                if (type.GetInterface("IProcess") == null)
                   continue;
                   // it implements IProcess. Create an instance
                      // of the object.
                object o = Activator.CreateInstance(type);
                   // create the parameter list, call it,
                   // and print out the return value.
                Console.WriteLine("    Calling Process() on {0}",
                            type.FullName);
                object[] args = new object[] {55};
                object result;
                result = type.InvokeMember("Process",
                   BindingFlags.Default |
                   BindingFlags.InvokeMethod,
                   null, o, args);
                Console.WriteLine("    Result: {0}", result);
            }
       }
    }
    public static void Main(String[] args)
    {
       foreach (string arg in args)
            ProcessAssembly(arg);
    }
}

process process1.dll process2.dll

Loading: process1.dll
  Found Class: MamaSoft.Processor1
    Calling Process() on MamaSoft.Processor1
In Processor1.Process(): 55
    Result: Raise the mainsail!
Loading: process2.dll
  Found Class: MamaSoft.Processor2
    Calling Process() on MamaSoft.Processor2
In Processor2.Process(): 55
    Result: Shiver me timbers!
  Found Class: MamaSoft.Unrelated

Dealing with Generics

Reflection can also be used with generic types. The simplest way to determine whether a particular type is generic is the new property of Type called IsGenericTypeDefinition. This property will return true only if the type is generic and the generic types have not been bound to a nongeneric type.

class Program
{
    static void Main(string[] args)
    {
       List<int> list = new List<int>();
       //will be false
       bool b1 = list.GetType().IsGenericTypeDefinition;
       //will be true
       bool b2 = list.GetType().GetGenericTypeDefinition().IsGenericTypeDefinition;
    }
}

In this case, the IsGenericTypeDefinition returns false for the type List<int>, which is a type that does not have any generic parameters. The method GetGenericTypeDefinition() can be used to get a reference from the constructed type List<int> back to the unbound generic type List<T>. The IsGenericTypeDefinition property returns true for this unbound generic type.

The generic arguments for a type or method can be accessed via the GetGenericArguments() method. Consider the following generic type:

class MyGenericClass<T> { }

The generic parameter can be displayed by the following code:

static void DumpGenericTypeParams(Type type)
{
    if (type.IsGenericTypeDefinition)
    {
       foreach (Type genericType in type.GetGenericArguments())
       {
            Console.WriteLine(genericType.Name);
       }
    }
}

The output from this code when run against typeof (MyGenericClass<>) is simply as follows:

T

While simply dumping out the type name may not be overly useful, various reflection methods exist to access information such as the constraints that apply to the generic parameters (Type.GetGenericParameterConstraints()) and to bind generic parameters to nongeneric types (Type.BindGenericParameters()).