| In this section, you modify the program in Listing 1.15 by adding comments. In no way does this vary the execution of the program; rather, providing comments within the code makes it more understandable. Listing 1.17 shows the new code, and Output 1.7 shows the corresponding output. Listing 1.17. Commenting Your Code Output 1.7. Hey you! Enter your first name: Inigo Enter your last name: Montoya Your full name is Inigo Montoya
|
In spite of the inserted comments, compiling and executing the new program produces the same output as before. Programmers use comments to describe and explain the code they are writing, especially where the syntax itself is difficult to understand, or perhaps a particular algorithm implementation is surprising. Since comments are pertinent only to the programmer reviewing the code, the compiler ignores comments and generates an assembly that is devoid of any trace that comments were part of the original source code. Table 1.2 shows four different C# comment types. The program in Listing 1.17 includes two of these. Table 1.2. C# Comment TypesComment Type | Description | Example |
|---|
Delimited comments | A forward slash followed by an asterisk, /*, identifies the beginning of a delimited comment. To end the comment use an asterisk followed by a forward slash: */. Comments of this form may span multiple lines in the code file or appear embedded within a line of code. The asterisks that appear at the beginning of the lines but within the delimiters are simply for formatting. | /*comment*/ | Single-line comments | Comments may also be declared with a delimiter comprising two consecutive forward slash characters: //. The compiler treats all text from the delimiter to the end of the line as a comment. Comments of this form comprise a single line. It is possible, however, to place sequential single-line comments one after another, as is the case with the last comment in Listing 1.17. | //comment | XML delimited comments | Comments that begin with /** and end with **/ are called XML delimited comments. They have the same characteristics as regular delimited comments, except that instead of ignoring XML comments entirely, the compiler can place them into a separate text file. XML delimited comments were only explicitly added in C# 2.0, but the syntax is compatible with C# 1.0. | /**comment**/ | XML single-line comments | XML single-line comments begin with /// and continue to the end of the line. In addition, the compiler can save single-line comments into a separate file with the XML delimited comments. | ///comment |
A more comprehensive discussion of the XML comments appears in Chapter 9, where I discuss the various XML tags that are explicitly part of the XML standard. Beginner Topic: Extensible Markup Language (XML) The Extensible Markup Language (XML) is a simple and flexible text format frequently used within web applications and for exchanging data between applications. XML is extensible because included within an XML document is information that describes the data, known as metadata. Here is a sample XML file. <?xml version="1.0" encoding="utf-8" ?> <body> <book title="Essential C# 2.0"> <chapters> <chapter title="Introducing C#"/> <chapter title="Control Flow"/> ... </chapters> </book> </body>
The file starts with a header indicating the version and character encoding of the XML file. After that appears one main "book" element. Elements begin with a word in angle brackets, such as <body>. To end an element, place the same word in angle brackets and add a forward slash to prefix the word, as in </body>. In addition to elements, XML supports attributes. title="Essential C# 2.0" is an example of an XML attribute. Note that the metadata (book title, chapter, and so on) describing the data ("Essential C# 2.0", "Control Flow") is included in the XML file. This can result in rather bloated files, but it offers the advantage that the data includes a description to aid in interpreting the data. |
|
