C# Tutorial - Dissecting Our Third Application – Comments

Comments within source code improve the readability of the code to a developer. They can serve several purposes, but should generally aid the developer to understand complex portions of source code, and/or give the developer an overview of what is happening in the source code.

When developing source code, comments should clarify what the source code is doing and not contradict it. This means that any changes in the code must be reflected in the comments.

If working with more than one developer, then a standard for comments should be established, so that the style is the same throughout the source code.

Single Line Comments

// indicates that whatever follows for the rest of the line is a comment and will be ignored by the compiler. The // can be used at the beginning of a line like this

// Get first number
Console.Write("Enter a whole number: ");

Or they can appear after code like this

value1 = Console.ReadLine();  // Get first number

Multiple Line Comments

A comment that spans more than a single line begins with the delimiter /* and ends with the delimiter */. What this means is that all text or code between the starting delimiter and the ending delimiter will be ignored by the compiler. A multiple-line comment does not have to span multiple lines. For example;

/* This is a comment */

But in general a multiple-line comment looks like this.

/* This
 * is a 
 * multiple-line
 * comment.
 */

A word of warning, it is a common mistake to forget the closing delimiter of a multiple-line comment which can cause a syntax error when compiling.

XML comments

C# supports embedded XML comments, which may be extracted using the C# compiler or a third-party tool. These tools allow the comments to be extracted to other formats such as HTML or Windows Help files. For example

/// <summary>
/// Main method of code
/// </summary>
/// <remarks>
/// No other methods are needed
/// </remarks>
/// <param name="args"></param>
public static void Main(string[] args)
{
  double cost = 340.0;
  Console.WriteLine( "The bike cost {0:C}", cost );
}

Each XML comment is denoted by three forward slashes (///) and is placed before the code item that is being documented. There are several comments that are supported by C#.

Tag Description
<c> The text within a description is to be formatted as single-line code
<code> The text within a description is to be formatted as multiple-line code
<example> Lets you specify an example of how to use a method
<exception> Lets you specify which exceptions can be thrown
<include> Lets you include documentation from other files
<param> Describes one of the parameters for a method
<permission> Lets you document the access of a member
<remarks> Lets you add information about a type that is supplementary to the summary
<returns> Describes the return value of a method
<summary> Summarises the item that is being documented
<value> Describes a property

You can generate an XML output from C# Express by opening the properties of the project. This can be done by either double-clicking on the Properties folder in the Solution Explorer, or by choosing App03 Properties from the Project menu. This will open the Project Properties dialog on a new tab in the environment. Select the Build tab and tick on the XML Documentation file option.

<< Previous Contents Next >>

© Publicjoe, 2008