Art of Commenting•Topic 4 of 4•~5 min
XML Documentation Comments
Developer Discovers Triple-Slash Comments; Suddenly Looks Like a Professional
In C# and .NET, XML documentation comments are special comments that can be automatically extracted to generate documentation. They're the difference between "some code I wrote" and "a professional API that others can actually use."
Essential XML Tags
/// <summary>
/// Calculates the total price including tax and discounts.
/// </summary>
/// <param name="basePrice">The original price before modifications</param>
/// <param name="taxRate">Tax rate as a decimal (e.g., 0.08 for 8%)</param>
/// <param name="discountCode">Optional discount code to apply</param>
/// <returns>The final calculated price</returns>
/// <exception cref="ArgumentException">
/// Thrown when basePrice is negative
/// </exception>
/// <example>
/// <code>
/// var total = CalculateTotal(100.00m, 0.08m, "SAVE10");
/// // Returns 97.20 (100 - 10% + 8% tax)
/// </code>
/// </example>
/// <remarks>
/// Discount is applied before tax calculation.
/// </remarks>
public decimal CalculateTotal(
decimal basePrice,
decimal taxRate,
string discountCode = null)
{
// Implementation
}Common XML Tags Reference
<summary>Brief description of the member
<param>Describes a method parameter
<returns>Describes the return value
<exception>Documents possible exceptions
<example>Shows usage examples
<remarks>Additional information
<see cref="...">Cross-reference to other members
<code>Inline code formatting
When to Use XML Documentation
✓Public APIs and libraries that others will consume
✓Complex methods with multiple parameters
✓Methods that throw exceptions under certain conditions
✓Any code that will be maintained by a team
Quick Check
What is the primary benefit of using XML documentation comments?