Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

What is the use of XML comments in C#

Tags:

c#

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
like image 217
Nayana Adassuriya Avatar asked Feb 12 '14 12:02

Nayana Adassuriya


People also ask

What are XML comments?

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.

What is the advantage of using XML comments?

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.

How do I comment out XML code?

The syntax for adding XML comments in your code is triple slashes /// followed by one of the supported XML tags.

What is XML documentation in C#?

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.


1 Answers

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:

enter image description here

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:

  • Your code is not clear enough and you should improve it (renaming, extracting classes or members) instead of adding comments
  • When code changes, comments often stay unchanged (programmers are lazy). So when time passes comments become obsolete and confusing.

Good comments should describe why you writing code instead of duplicating what code is doing.

like image 134
Sergey Berezovskiy Avatar answered Oct 06 '22 04:10

Sergey Berezovskiy