C# 4 and .NET 4

Using Comments ❘ 53
This displays as .23, because the # symbol is ignored if there is no character in that place, and zeros will
either be replaced by the character in that position if there is one or be printed as a zero.
using CommenTs
The next topic — adding comments to your code — looks very simple on the surface, but can be complex.
internal Comments within the source files
As noted earlier in this chapter, C# uses the traditional C-type single-line (//...) and multiline (/* ... */)
comments:
// This is a singleline comment
/* This comment
spans multiple lines. */
Everything in a single-line comment, from the // to the end of the line, will be ignored by the compiler,
and everything from an opening /* to the next */ in a multiline comment combination will be ignored.
Obviously, you can’t include the combination */ in any multiline comments, because this will be treated as
the end of the comment.
It is actually possible to put multiline comments within a line of code:
Console.WriteLine(/* Here's a comment! */ "This will compile.");
Use inline comments with care because they can make code hard to read. However, they can be useful when
debugging if, say, you temporarily want to try running the code with a different value somewhere:
DoSomething(Width, /*Height*/ 100);
Comment characters included in string literals are, of course, treated like normal characters:
string s = "/* This is just a normal string .*/";
Xml documentation
In addition to the C-type comments, illustrated in the preceding section, C# has a very neat feature that
we want to highlight: the ability to produce documentation in XML format automatically from special
comments. These comments are single-line comments but begin with three slashes (///) instead of the usual
two. Within these comments, you can place XML tags containing documentation of the types and type
members in your code.
The tags in the following table are recognized by the compiler.
Tag
desCriPTion
Marks up text within a line as code, for example int i = 10;.
Marks multiple lines as code.
Marks up a code example.
Documents an exception class. (Syntax is verified by the compiler.)
Includes comments from another documentation file. (Syntax is verified by
the compiler.)
Inserts a list into the documentation.
Marks up a method parameter. (Syntax is verified by the compiler.)
Indicates that a word is a method parameter. (Syntax is verified by the compiler.)
Documents access to a member. (Syntax is verified by the compiler.)
continues
www.it-ebooks.info