Introduction Commenting in any programming langauge is important part of development because it helps understanding the code better and supplements when working as a part of the large team and so C# being a langauge of the modern era has some of the best support any project needs as far as the documentation is concerned. There are three types of commenting syntax in C# multiline, single-line, and XML Tags. The main aim of this article is not to tell you how to comment because even when writing the first program of Hello World you would know how to be doing this and so the main part of the article starts with XML Documentation Comments but you can always read the next couple of sections without much of a stress. 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. Code: /* * FileName: test.cs * Author: Sanskruti */ The compiler understands this as comment and ignores comments when parsing the source code for compilation. As it is not parsed anything and everything is correct. We have lots of tools which even do the grammar and spell check in the comments to make them error free but I would like not to be discussing that as of now and also its beyond the scope of this article. Some languages allow embedded multiline comments, but C# does not support that. Consider the following example: Code: /* Filename: test.cs Author: Sanskruti /* Initial Implementation: 01/01/07 Change 1: 01/15/07 Change 2: 03/10/07 */ */ 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 The main aim of the single line comment is to give something meaning ful to some of the executable statements. Single-line comments allow narrative on only one line at a time and ends as soon as a newline is began. 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 1, 3, and 6 of Listing 1 show single-line comments. These lines are repeated here for convenience. Code: // Program start class public class SanskrutiAuthor { // Main begins program execution public static void Main() { // Write to console System.Console.WriteLine("Sanskruti, Author!"); } } 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 web browser. Before proceding further I would like to show you XML Documentation Tags <c> a way to indicate that text within a description should be marked as code<code> a way to indicate multiple lines as code<example> lets you specify an example of how to use a method or other library member<exception> lets you document an exception class<include> lets you refer to comments in another file, using XPath syntax, that describe the types and members in your source code.<list> Used to insert a list into the documentation file<para> Used to insert a paragraph into the documentation file<param> Describes a parameter<paramref> gives you a way to indicate that a word is a parameter<permission> lets you document access permissions<remarks> where you can specify overview information about the type<returns> describe the return value of a method<see> lets you specify a link<seealso> lets you specify the text that you might want to appear in a See Also section<summary> used for a general description<value> lets you describe a property To provide a summary of an item, use the <summary> tag. Here's what one might look like for a Main() method: Code: /// <summary> /// Something about what the <c>MySomeFunction</c> does /// with some of the sample like /// <code> /// Some more code statement to comment it better /// </code> /// For more information seee <see cref="http://www.go4expert.com"/> /// </summary> /// <param name="someObj">What the input to the function is</param> /// <returns>What it returns</returns> public bool MySomeFunction(object someObj) { } Documentation comments can be extremely useful in keeping documentation up-to-date.
