In Visual C#, statements are terminated with a semicolon (;). C# is a free-form language in which a statement can span multiple lines of source code and can start in any position. Conversely, multiple statements can be combined on a single source code line. Here are some variations:

int variablea =
          variableb +
                variablec;

variableb = variableb + 3; variablec = variablec + 1;

++variableb;

Dot syntax connotes membership. The dot character (.) binds a target to a member, in which the target can be a namespace, type, structure, enumeration, interface, or object. This assumes the member is accessible. Membership is sometimes nested and described with additional dots.

Here is the syntax for the dot punctuator:

Target.Member

This is an example of the dot punctuator:

System.Windows.Forms.MessageBox.Show("A nice day!");

System, Windows, and Forms are namespaces. MessageBox is a class. Show, the most nested member, is a static method.

The colon punctuator primarily delimits a label, indicates inheritance, indicates interface implementation, sets a generic constraint, or is part of a conditional operator.

Labels are tags for locations to which program execution can be transferred. A label is terminated with a colon punctuator (:). The scope of a label is limited to the containing block and any nested block. There are various methods for transferring to a label. For example, you can jump to a label with the goto statement. Within a switch block, you also can use the goto statement to jump to a case or default statement.

Here is the syntax for the label punctuator:

label_identifier: statement

A statement must follow a label, even if it’s an empty statement.

Here is an example of a goto statement:

   public static void Main() {
       goto one;
       // do stuff
one:   Console.WriteLine("one");
   }

The comma punctuator delimits array indexes, function parameters, types in an inheritance list, statement clauses, and other language elements. The comma punctuator separates clauses of a for statement in the following code:

for (int iBottom = 1, iTop = 10; iBottom < iTop; ++iBottom, --iTop) {
    Console.WriteLine("{0}x{1} {2}", iBottom, iTop, iBottom*iTop);
}

A statement clause is a substatement in which multiple statement clauses can be combined into a single statement. Statement clauses are not always available—check documentation related to the language artifact to be sure.

Single-line comments start at the comment symbol and conclude at the line terminator, as follows:

Console.WriteLine(objGreeting.French); // Display Hello (French)

Delimited comments, also called multi-line or block comments, are bracketed by the /* and */ symbols. Delimited comments can span multiple lines of source code:

/*
        Class Program: Programmer Donis Marshall
*/
class Program {
    static int Main(string[] args) {
        Greeting objGreeting = new Greeting();
        Console.WriteLine(objGreeting.French); // Display Hello (French)
        return 0;
    }
}

Documentation comments apply a consistent format to source code comments and use XML tags to classify comments. With the documentation generator, documentation comments are exportable to an XML file. The resulting file is called the documentation file, which is identified in the Visual Studio project options. IntelliSense and the Object Browser use information in this file.

Single-line documentation comments are partially automated in the Visual Studio IDE. The Visual Studio IDE has Smart Comment Editing, which automatically continues or creates a skeleton for a document comment after initially entering the /// symbol. For example, the following code snippet shows sample code with single-line documentation comments. After entering an initial ///, Smart Comment Editing completed the remainder of the comment framework, including adding comments and XML tags for the type, methods, method parameter, and return value. You only need to update the comment framework with specific comments and additional comment tags that might be helpful:

/// <summary>
///
/// </summary>
class Program {
    /// <summary>
    ///
    /// </summary>
    /// <param name="args"></param>
    /// <returns></returns>
    static int Main(string[] args) {
         Greeting objGreeting = new Greeting();
         Console.WriteLine(objGreeting.French); // Display Hello (French)
         return 0;
    }
}

Here are the documentation comments with added details:

/// <summary>
/// Starter class for Simple HelloWorld
/// </summary>
class Program {
    /// <summary>
    /// Program Entry Point
    /// </summary>
    /// <param name="args">Command Line Parameters</param>
    /// <returns>zero</returns>
    static int Main(string[] args) {
          Greeting objGreeting = new Greeting();
          Console.WriteLine(objGreeting.French);   // Display Hello (French)
          return 0;
    }
}

The C# compiler is a documentation generator. The /doc compiler option instructs the compiler to generate the documentation file. This can be done using the Visual Studio IDE. Select Project Properties from the Project menu. In the Properties window, select the Build tab. Toward the bottom of the Build pane (shown in Figure 1-2), you can specify the name of the XML documentation file.

Figure 1-2. The Build pane of the Project Settings window

For the preceding source file, this is the documentation file generated by the C# compiler:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ConsoleApplication1</name>
    </assembly>
    <members>
        <member name="T:ConsoleApplication1.Program">
            <summary>
            Starter class for Simple HelloWorld
            </summary>
        </member>
        <member name="M:ConsoleApplication1.Program.Main(System.String[])">
            <summary>
            Program Entry Point
            </summary>
            <param name="args">Command Line Parameters</param>
            <returns>zero</returns>
        </member>
    </members>
</doc>

The documentation generator prefixes IDs to element names of the member name tag. In the preceding documentation file, T is the prefix for a type, whereas M is a prefix for a method. Here’s a listing of IDs:

Multi-line documentation tags are an alternative to single-line documentation tags. Smart Comment Editing is not available with multi-line documentation tags. You must enter the documentation tags explicitly. However, Intellisense is available. Multi-line documentation comments must adhere to a degree of consistency, which is explained in the article titled "Delimiters for Documentation Tags (C# Programming Guide)," in Visual Studio Help (ms-help://MS.VSCC.v90/MS.MSDNQTR.v90.en/dv_csref/html/9b2bdd18-4f5c-4c0b-988e-fb992e0d233e.htm).

Here is an example of delimited documentation tags:

/**
 *<summary>this is an example.</summary>
*/

The declarative preprocessor directives are #define and #undef, which define and undefine a preprocessor symbol, respectively. Defined symbols are implicitly true, whereas undefined symbols are false. Declarative symbols must be defined in each compilation unit where the symbol is referenced. Undeclared symbols default to undefined and false. The #define and #undef directives must precede any source code. Redundant #define and #undef directives have no effect.

Preprocessor symbols can also be set as a compiler option. In the Build pane of the Project Properties dialog box, you can define one or more symbols in the Conditional Compilation Symbols text box. This is shown in Figure 1-3. Other preprocessor symbols, such as DEBUG and TRACE, are commonly set implicitly as a compiler option.

Figure 1-3. The Conditional Compilation Symbols text box

Here is the syntax for declarative preprocessor directives:

#define identifier
#undef identifier

Conditional preprocessor directives are the #if, #else, #elif, and #endif directives, which exclude or include source code. A conditional preprocessor directive begins with #if and ends with #endif. The intervening conditional preprocessing directives, #else and #elif, are optional.

Here is the syntax for conditional preprocessor directives:

#if Boolean_expression
#elif Boolean_expression
#else
#endif

The Boolean_expression of the #if and #elif directive is a combination of preprocessor symbols and Boolean operators (! == != && ||). If the Boolean_expression is true, the source code immediately after the #if or #elif directive and before the next conditional preprocessor directive is included in the compilation. If the Boolean_expression is false, the source code is excluded from source compilation. The #else directive can be added to a #if or #elif combination. If the Boolean_expression of #if and #elif is false, the code following the #else is included in the compilation. When true, the source code after the #else is not included. Here’s sample code with preprocessor symbols and related directives:

#define DEBUGGING

using System;

namespace Donis.CSharpBook {
    class Starter{
#if DEBUGGING
        static void OutputLocals() {
              Console.WriteLine("debugging...");
        }
#endif
        static void Main() {
#if DEBUGGING
            OutputLocals();
#endif
        }
    }
}

Finally, the #elif directive is a combination of an else and if conditional preprocessor directive. It is matched with the nearest #if directive:

#if expression
    source_code
#elif expression
    source_code
#else
    source_code
#endif

Diagnostic directives include the #error, #warning, and #pragma directives. The #error and #warning directives display error and warning messages, respectively. The diagnostic messages are displayed in the Error List window of the Visual Studio IDE. Similar to standard compilation errors, an #error directive prevents the program from compiling successfully; a #warning directive does not prevent the program from successfully compiling unless Treat Warnings As Error is set as a compiler option. You can use conditional directives to conditionally apply diagnostic directives.

Here is the syntax for diagnostic directives:

#error error_message
#warning error_message

The error_message is of string type and is optional.

The #pragma directive disables or enables compilation warnings. When disabled, the warning or error is suppressed and will not appear in the Error List window. This is useful for suppressing an unwanted warning or error temporarily or permanently.

Here is the syntax for pragma directives:

#pragma warning disable warning_list
#pragma warning restore warning_list

The warning_list contains one or more warnings delimited with commas. A disabled warning remains disabled until it is restored or the compilation unit ends.

The following code demonstrates the pragma warning directive. In this example, the 219 warning (Variable Is Assigned But Its Value Is Never Used) is initially disabled and then restored. Therefore a warning is received about variableb but not variablea.

class Starter
{
#pragma warning disable 219
    static void Main()
    {
        int variablea = 10;
    }
#pragma warning restore 219

    static void FuncA()
    {
        int variableb = 20;
    }
}

Region directives mark sections of source code. The #region directive starts a region, whereas the #endregion directive ends the region. Region directives can be nested. The Visual Studio IDE outlines the source code based on region directives. In Visual Studio, you can collapse or expand regions of source code.

Here is the syntax for region directives:

#region identifier
source_code
#endregion

Line directives modify the line number reported in subsequent compiler errors and warnings. There are three versions of the line directive.

Here is the syntax for line directives:

#line line_number source_filename
#line default
#line hidden

The first #line directive renumbers the source code from the location of the directive until the end of the compilation unit is reached or overridden by another #line directive. In the following code, the #line directive resets the current reporting line to 25:

#line 25
static void Main() {
    Console.WriteLine("#line application");
    int variablea=10;  // 219 warning
}

The #line default directive undoes any previous #line directives. The line number is then reset to the natural line number.

The #line hidden directive is only tangentially related to the line number. This directive does not affect the line number; it hides source code from the debugger when stepping. The source code is skipped until the next #line directive is encountered. This is helpful in stepping through source code. Hidden code is essentially stepped over. For example, when stepping in the following source, the for loop is stepped over. The #line default directive then returns normal stepping.

    static void Main()
    {
        int variablea = 10;
        variablea++;
#line hidden
        for (int i = 0; i < 5; ++i)
        {
            variablea++;
        }
#line default
        Console.WriteLine(variablea);
    }

Unary operators have a single operand. Table 1-5 lists the unary operators.

Here are some more details on unary parameters:

Binary operators have a left and right operand. Table 1-6 details the binary operators.

Here’s more information on binary operators:

Compound operators combine an assignment and another operator. If the expanded expression is variable = variable operator value, the compound operator is variable operator= value. For example, assume that we want to code the following:

variable = variable + 5;

The preceding statement is equivalent to this:

variable += 5;

Compound operations are a shortcut and are never required in lieu of the expanded statement. Table 1-7 lists the compound operators.

Boolean expressions evaluate to true or false. Unlike C++, the integer values of nonzero and zero are not equivalent to a Boolean true or false.

There are two versions of the logical and and or operators. The && and || operators support short-circuiting, whereas & and | do not. What is short-circuiting? If the result of the expression can be determined with the left side, the right side is not evaluated. Without disciplined coding practices, short-circuiting might cause unexpected side effects.

Next is an example of possible short-circuiting. If FunctionA evaluates to false, the entire Boolean expression is false. Therefore the right-hand expression (FunctionB) is not evaluated. If calling FunctionB has a required side effect, short-circuiting in this circumstance could cause a bug.

if (FunctionA() && FunctionB()) {

}

Table 1-8 shows the Boolean operators.

The conditional operator is the sole ternary operator in C# and is an abbreviated if else statement.

Here is the syntax of the conditional operator:

Boolean_expression ? true_statement : false_statement

This is the conditional operator in source code:

char e = (x > 0) ? '>' : '<'

Type operators act on a type. The as and is operators are binary operators, while the typeof operator is unary. Table 1-9 lists the type operators.

Pointer operators are available in unsafe mode. This allows C# developers to use C++ style pointers. The unsafe compiler option sets unsafe mode. From the Visual Studio IDE, you can choose the Allow Unsafe Mode option in the Project Properties dialog box on the Build pane. Table 1-10 lists the pointer operators.

Here is some sample code using pointers:

static void Main(string[] args)
{
   unsafe {
         int variable = 10;
         int* pVariable = &variable;
         Console.WriteLine("Value at address is {0}.",
               *pVariable);
   }
}

A more extensive review of pointers is presented later in the book in Chapter 19, "Unsafe Code."

The miscellaneous operators are unary but do not otherwise fit into a clear category. Table 1-11 lists the miscellaneous operators.