What is the use of XML comments in C# than signal line and multiple line comments.
i.Single line
Eg:
//This is a Single line comment
ii. Multiple line (/* */)
Eg:
/*This is a multiple line comment
We are in line 2
Last line of comment*/
iii. XML Comments (///).
Eg:
/// summary;
/// Set error message for multilingual language.
/// summary
XML comments are similar to HTML comments. The comments are added as notes or lines for understanding the purpose of an XML code. Comments can be used to include related links, information, and terms. They are visible only in the source code; not in the XML code. Comments may appear anywhere in XML code.
XML comments help speed development by providing IntelliSense on custom methods and other code constructs. XML comments encourage code reuse by providing a path to generate API style reference documentation from your source code.
The syntax for adding XML comments in your code is triple slashes /// followed by one of the supported XML tags.
The C# compiler combines the structure of the C# code with the text of the comments into a single XML document. The C# compiler verifies that the comments match the API signatures for relevant tags. Tools that process the XML documentation files can define XML elements and attributes specific to those tools.
From XML Documentation Comments (C# Programming Guide):
When you compile with the /doc option, the compiler will search for all XML tags in the source code and create an XML documentation file.
Also XML comments used by Visual Studio for IntelliSense:
/// <summary>
/// This class performs an important function.
/// </summary>
public class MyClass{}
Will give you nice hints when you are typing code or hovering cursor over member which has xml comments:
NOTE: Usually you should add xml comments only to publicly visible types or members. If member is internal or private, then it's good, but not necessary. There is nice tool GhostDoc (available as extension to Visual Studio) which can generate XML comments from type or member name. It's nice to check if you have good naming - if generated comment is not clear, then you should improve name of member.
I also suggest use simple (non-xml) comments as little, as possible. Because comment is a form of code duplication - it duplicates information which you already have in your code. And here is two problems:
Good comments should describe why you writing code instead of duplicating what code is doing.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With