Microsoft Visual C#.NET 2003 Kick Start

Comments in C#

As you know, commenting your code helps make it a good deal clearer. C# supports three types of comments, C++-style // comments, C-style /*...*/ comments, and XML-style /// comments.

// Comments

The // style of comments are the most commonly used in C#, as in C++. These comments are single-line comments, making the compiler ignore the text following the // :

class ch01_01 { // Display the message. static void Main() { System.Console.WriteLine("Hello from C#."); } }

These comments don't have to be on their own line, of course; you can add them to any line, and the compiler will stop looking for code when it reaches the // on a line:

class ch01_01 { static void Main() { System.Console.WriteLine("Hello from C#."); // Show message. } }

/*...*/ Comments

/*...*/ comments are multi-line comments; when the compiler reaches /* , it stops reading and compiling code until it reaches the */ . Here's an example:

class ch01_01 { /* Display the message. */ static void Main() { System.Console.WriteLine("Hello from C#."); } }

Multi-line comments like this are often used to create documentation blocks, which are usually outlined in asterisks like this:

class ch01_01 { /* * * Display the message. * * */ static void Main() { System.Console.WriteLine("Hello from C#."); } }

/// Comments

/// comments are XML documentation comments . These comments are stripped out by various C# tools and treated as XML-style documentation, stored in an XML file. You write your comments as XML elements, like this:

class ch01_01 { /// <summary> /// Display the message. /// </summary> static void Main() { System.Console.WriteLine("Hello from C#."); } }

You can then use the /doc switch with the command-line compiler to strip the XML documentation out of your source code and into a file (named doc.xml here) like this:

C:\>csc ch01_01.cs /doc:doc.xml

Here's what doc.xml looks like:

<?xml version="1.0"?> <doc> <assembly> <name>t</name> </assembly> <members> <member name="M:ch01_01.Main"> <summary> Display the message. </summary> </member> </members> </doc>

In this way, you can make your source code almost self-documenting .

You can also create XML documentation in Visual Studio by clicking the project's icon in the Solution Explorer (see Figure 1.2), selecting the View, Property Pages menu item, clicking the Configuration Properties folder, and then clicking the Build item in that folder. Enter a name for the XML Documentation File property and click OK.

Besides creating XML documentation files, you can also create Web reports that present the documentation in your code as a clickable set of nodes. When you're creating a Web report, you can use these XML elements in your /// comments:

• <summary></summary> provides a summary.

• <remarks></remarks> gives overview information.

• <param></param> describes a parameter for a method call.

• <returns></returns> Describes the return value of a method.

• <newpara></newpara> starts a new paragraph.

To build a Web report for your project in Visual Studio .NET, select Tools, Build Comment Web Pages; you can see a Web report for the example in Figure 1.5 (where the text from the XML comment appears in the lower-right corner in the center window).

You can also create XML-style documentation comments with /**...*/ multi-line comments, not just the /// single-line style, like this:

class ch01_01 { /** <summary> Display the message. </summary> */ static void Main() { System.Console.WriteLine("Hello from C#."); } }