Commenting your C# code for documentation
Some of us will have experienced with coding documentation. C# and Visual Studio gives us the ability to maintain code and it’s documentation in the same file, which makes the whole development a lot easier. VS.NET provides specially marked and structured comments within the code and help to build them into an XML file. There are many different tools that can be used to generate human-readable documentation in a variety of forms including web pages, MSDN style documentation and etc...
To document any element in a C#, you tag the element with XML elements. XML tags are added to source code by prefixing the XML comment lines with three forward slashes. Visual Studio will automatically put in a documentation outline whenever three forward slashes are typed within C# source code file.
/// <summary></summary>
/// <param name="Employee "></param>
public void Save(object Employee)
{
}
|
The Save code comments are inserted as default. The C# compiler reads documentation comments in your code and formats them as XML into a file. You are required to enable “XML documentation file” in Visual Studio properties to generate the XML file.
The XML comments tags
The following are some important XML comment tags supported in C#. Note that the content of each element should be written between its opening and closing tags, and some of the tags also take further attributes.
|
Tags
|
Description
|
|
<summary>
|
holds overview information about any documental element. This tag should be used to describe a member for a type.
|
|
<remarks>
|
can be used to supply additional information about a method or class, supplementing the details given in the summary tag.
|
|
<param name="name">
|
should be used in the comment for a method declaration to describe one of the parameters for the method.
|
|
<returns>
|
should be used in the comment for a method declaration to describe the return value.
|
|
<exceptions cref="type">
|
lets you specify which exceptions can throw by the element.
|
|
<example>
|
lets you specify an example of how to use a method or other library member. Commonly, this would involve use of the code tag.
|
|
<code>
|
gives you a way to indicate multiple lines as code. Generally used in conjunction with the ‘example’ element.
|
|
<Value>
|
lets you describe a property.
|
|
<c>
|
gives you a way to indicate that text within a description should be marked as code.
|
|
<paramref name="name">
|
gives you a way to indicate that a word is a parameter. This tag can be used to refer to a method's argument elsewhere within the method's XML comments.
|
|
<para>
|
for use inside a tag, text within the tags should be formatted within a paragraph.
|
|
<list type = ”bullet” | “number” | “table”>
|
allows bulleted or numbered lists or tables to be added to XML comments.
<list type="table">
<listheader>
<term>ID</term>
<description>Name</description>
</listheader>
<item>
<term>001</term>
<description>Karim</description>
</item>
<item>
<term>002</term>
<description>Rahim</description>
</item>
</list>
|
*Note that here are only important tags, there are also other tags are available.
Once the XML comments have been added to the code, it is useful to be able to do something with them. Code documented in a standard format is a clear benefit. You can get great technical documentation at a level so close to the code.
Expectantly this piece of writing will cheer you to add comments to your C# code. Whether you are functioning for a business or for yourself, well commented code always looks professional. It can also give you the aggressive edge over other developers and businesses.