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: CSharp
/*
* FileName: test.cs
* Author: Sanskruti
*/
Code: CSharp
/*
Filename: test.cs
Author: Sanskruti
/*
Initial Implementation: 01/01/07
Change 1: 01/15/07
Change 2: 03/10/07
*/
*/
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: CSharp
// Program start class
public class SanskrutiAuthor
{
// Main begins program execution
public static void Main()
{
// Write to console
System.Console.WriteLine("Sanskruti, Author!");
}
}
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 propertyTo provide a summary of an item, use the <summary> tag. Here's what one might look like for a Main() method:
Code: CSharp
/// <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)
{
}
