2.1. The Layout of a C Program

2.1. The Layout of a C# Program

Figure 2-1 illustrates some of the basic features of a C# program.

Figure 2-1. Basic elements of a C# program

The code in Figure 2-1 consists of a class MyApp that contains the program logic and a class Apparel that contains the data. The program creates an instance of Apparel and assigns it to myApparel. This object is then used to print the values of the class members FabType and Price to the console. The important features to note include the following:

1. The using statement specifies the namespace System. Recall from Chapter 1, "Introduction to .NET and C#," that the .NET class libraries are organized into namespaces and that the System namespace contains all of the simple data types. The using statement tells the compiler to search this namespace when resolving references, making it unnecessary to use fully qualified names. For example, you can refer to label rather than System.Web.UI.WebControls.Label.

2. All programming logic and data must be contained within a type definition. All program logic and data must be embedded in a class, structure, enum, interface, or delegate. Unlike Visual Basic, for instance, C# has no global variable that exists outside the scope of a type. Access to types and type members is strictly controlled by access modifiers. In this example, the access modifier public permits external classes such as MyApp to access the two members of the Apparel class.

3. A Main() method is required for every executable C# application. This method serves as the entry point to the application; it must always have the static modifier and the M must be capitalized. Overloaded forms of Main()define a return type and accept a parameter list as input.

   Return an integer value:

    static int Main() {    return 0; // must return an integer value } 

   
   

   Receive a list of command-line arguments as a parameter and return an integer value:

    static int Main(string[] args) {    // loop through arguments    foreach(string myArg in args)       Console.WriteLine(myArg);    return 0; } 

   
   

   The parameter is a string array containing the contents of the command line used to invoke the program. For example, this command line executes the program MyApparel and passes it two parameter values:

    C:\> MyApparel 5 6 

   
   

Core Note

The contents of the command line are passed as an argument to the Main() method. The System.Environment.CommandLine property also exposes the command line's contents.

General C# Programming Notes

Case Sensitivity

All variable and keywords are distinguished by case sensitivity. Replace class with Class in Figure 2-1 and the code will not compile.

Naming Conventions

The ECMA standard provides naming convention guidelines to be followed in your C# code. In addition to promoting consistency, following a strict naming policy can minimize errors related to case sensitivity that often result from undisciplined naming schemes. Table 2-1 summarizes some of the more important recommendations.

Table 2-1. C# Naming Conventions

Type	Case	Notes and Examples
Class	Pascal	Use noun or noun phrases. Try to avoid starting with I because this is reserved for interfaces. Do not use underscores.
Constant	Pascal	public const double GramToPound = 454.0 ;
Enum Type	Pascal	Use Pascal case for the enum value names. Use singular name for enums. public enum WarmColor { Orange, Yellow, Brown}
Event	Pascal	The method that handles events should have the suffix EventHandler. Event argument classes should have the suffix EventArgs.
Exception	Pascal	Has suffix Exception.
Interface	Pascal	Has prefix of I. IDisposable
Local Variable	Camel	Variables with public access modifier use Pascal int myIndex.
Method	Pascal	Use verb or verb phrases for name.
Namespace	Pascal	Do not have a namespace and class with the same name. Use prefixes to avoid namespaces having the same name. For example, use a company name to categorize namespaces developed by that company. Acme.GraphicsLib
Property	Pascal	Use noun or noun phrase.
Parameter	Camel	Use meaningful names that describe the parameter's purpose.

Note that the case of a name may be based on two capitalization schemes:

1. Pascal. The first character of each word is capitalized (for example, MyClassAdder).

2. Camel. The first character of each word, except the first, is capitalized (for example, myClassAdder).

The rule of thumb is to use Pascal capitalization everywhere except with parameters and local variables.

Commenting a C# Program

The C# compiler supports three types of embedded comments: an XML version and the two single-line (//) and multi-line (/* */) comments familiar to most programmers:

 //   for a single line  /*   for one or more lines                       */ /// <remarks> XML comment describing a class </remarks> 

An XML comment begins with three slashes (///) and usually contains XML tags that document a particular aspect of the code such as a structure, a class, or class member. The C# parser can expand the XML tags to provide additional information and export them to an external file for further processing.

The <remarks> tag shown in Figure 2-1 is used to describe a type (class). The C# compiler recognizes eight other primary tags that are associated with a particular program element (see Table 2-2). These tags are placed directly above the lines of code they refer to.

Table 2-2. XML Documentation Tags

Tag	Description
<example>	Text illustrating an example of using a particular program feature goes between the beginning and ending tags.
<exception cref="Excep">	cref attribute contains name of exception. ///<exceptioncref="NoParmException"> </exception>
<include file="myXML">	file attribute is set to name of another XML file that is to be included in the XML documentation produced by this source code.
<param name="parm1">	name attribute contains the name of the parameter.
<permission cref= "">	Most of the time this is set to the following: ///<permissioncref="System.Security.Permis- sionSet"> </permission>
<remarks>	Provides additional information about a type not found in the <summary> section.
<returns>	Place a textual description of what is returned from a method or property between the beginning and ending tags.
<seealso cref="price">	The cref attribute is set to the name of an associated type, field, method, or other type member.
<summary>	Contains a class description; is used by IntelliSense in VisualStudio.NET.

The value of the XML comments lies in the fact that they can be exported to a separate XML file and then processed using standard XML parsing techniques. You must instruct the compiler to generate this file because it is not done by default.

The following line compiles the source code consoleapp.cs and creates an XML file consoleXML:

 C:\> csc consoleapp.cs /doc:consoleXML.xml 

If you compile the code in Figure 2-1, you'll find that the compiler generates warnings for all public members in your code:

 Warning CS1591: Missing XML comment for publicly visible type ... 

To suppress this, add the /nowarn:1591 option to the compile-line command. The option accepts multiple warning codes separated with a comma.

Core Note

Many documentation tools are available to transform and extend the C# XML documentation output. One of the most advanced is NDoc (ndoc.sourceforge.net), an open source tool that not only formats the XML but uses reflection to glean further information about an assembly.