I've mostly used // for comments, and I don't mind writing fairly detailed explanations. However, while reviewing a larger C# codebase, I started seeing
blocks above classes and methods. What are these used for, and when should I prefer them over regular // comments? Searches keep bringing up HTML-related results, so I'd appreciate an explanation of how C# XML documentation works.
3 Answers
They’re a standardized, tool-friendly form of comments. C# supports tags such as
XML documentation can be included in the compiled assembly’s accompanying documentation file, which libraries and tools can use to generate API docs. That’s why many package libraries include descriptions for their types, methods, parameters, and return values. In Visual Studio, typing three forward slashes (///) immediately before a declaration usually generates a documentation template automatically.
Those are XML documentation comments. Visual Studio and other IDEs read them and display the text in tooltips and IntelliSense when someone hovers over a class or method. They’re especially useful for explaining the purpose of a public API without requiring someone to inspect the method’s implementation. Regular // comments are still fine for notes about the code’s internals.
That clears it up—seeing the tags in a shared codebase made me think they were related to HTML. I’ll try using /// when documenting public methods.