Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
Comments
There are three types of commenting syntax in C#—multiline, single-line, and XML.
Multiline Comments
Multiline comments have one or more lines of narrative within a set of comment delimiters. These comment delimiters are the begin comment /* and end comment */ markers. Anything between these two markers is considered a comment. The compiler ignores comments when reading the source code. Lines 1 through 4 of Listing 1 show a multiline comment. For convenience, Lines 1 through 4 of Listing 1 are repeated here.
1: /* 2: * FileName: HowdyParner.cs 3: * Author: Joe Mayo 4: */
Some languages allow embedded multiline comments, but C# does not. Consider the following example:
1: /* 2: Filename: HowdyPartner.cs 3: Author: Joe Mayo 4: /* 5: Initial Implementation: 04/01/01 6: Change 1: 05/15/01 7: Change 2: 06/10/01 8: */ 9: */
The begin comment on Line 1 starts a multiline comment. The second begin comment on line 4 is ignored in C# as just a couple characters within the comment. The end comment on Line 8 matches with the begin comment on line 1. Finally, the end comment on Line 9 causes the compiler to report a syntax error because it doesn't match a begin comment.
Single-Line Comments
Single-line comments allow narrative on only one line at a time. They begin with the double forward slash marker, //. The single-line comment can begin in any column of a given line. It ends at a new line or carriage return. Lines 6, 9, and 12 of Listing 1 show single-line comments. These lines are repeated here for convenience.
6: // Program start class
7: public class HowdyPartner
8: {
9: // Main begins program execution
10: public static void Main()
11: {
12: // Write to console
13: System.Console.WriteLine("Howdy, Partner!");
Single-line comments may contain other single-line comments. Because they're all on the same line, subsequent comments will be treated as comment text.
XML Documentation Comments
XML documentation comments start with a triple slash, ///. Comments are enclosed in XML tags. The .NET C# compiler has an option that reads the XML documentation comments and generates XML documentation from them. This XML documentation can be extracted to a separate XML file. Then XML style sheets can be applied to the XML file to produce fancy code documentation for viewing in a browser. Table 1 shows all standard XML documentation tags.
Table 1 XML Documentation Tags
|
<c> |
<code> |
<example> |
<exception> |
<list> |
|
<param> |
<paramref> |
<permission> |
<remarks> |
<returns> |
|
<see> |
<seealso> |
<summary> |
<value> |
|
To provide a summary of an item, use the <summary> tag. Here's what one might look like for a Main() method:
/// <summary> /// Prints "Howdy, Partner" to the console. /// </summary>
Documentation comments can be extremely useful in keeping documentation up-to-date. How many programmers do you know who conscientiously update their documentation all the time? Seriously, when meeting a tight deadline, documentation is the first thing to go. Now there's help. While in the code, it's easy to update the comments, and the resulting XML file is easy to generate. The following line of code will extract documentation comments from the HowdyPartner.cs file and create an XML document named HowdyPartner.xml.
csc /doc:HowdyPartner.xml HowdyPartner.cs
For C++ Programmers
C# has XML documentation comments that can be extracted to separate XML files. Once in an XML file, XML style sheets can be applied to produce fancy code documentation for viewing in a browser.