Comments (C#)

C# has three types of comment syntax.

// For multi-line explanations, add // at the start of each line.

/* This is a block comment.
   Use it when you want to write a comment spanning multiple lines.
   You cannot nest /* inside a block comment. */

/// <summary>
/// This is an XML documentation comment. Write it directly before a class, method, or property.
/// </summary>
/// <param name="paramName">Description of the parameter.</param>
/// <returns>Description of the return value.</returns>
/// <remarks>Additional notes.</remarks>
/// <example>Usage example.</example>

Type	Syntax	Common Use
Single-line comment	//	Add a short explanation next to or above a line of code.
Block comment	/* */	Multi-line explanations. Temporarily disabling code (commenting out).
XML documentation comment	///	Document the public API of classes, methods, and properties. Used by IDEs for tooltips and XML documentation generation.

Tag	Description
<summary>	Describes the overview of a class, method, or property. This is the most fundamental tag.
<param name="name">	Describes a method parameter. Specify the argument name in the name attribute.
<returns>	Describes the return value.
<remarks>	Provides supplementary information or notes.
<example>	Provides a usage example.
<exception cref="TypeName">	Describes exceptions that may be thrown.
<see cref="TypeName">	Creates a reference link to another class or member.
<code>	Formats inline code within documentation.

CommentBasic.cs

A sample showing single-line and block comment usage.

using System;

class CommentBasic {
	static void Main() {

		// Everything after // until the end of the line is treated as a comment.
		string name = "Goku"; // You can also place a comment to the right of code.

		// For multi-line explanations, add // at the start of each line.
		// Here we initialize Goku's power level.
		// Later it will be multiplied by the transformation factor.
		int power = 9000;

		Console.WriteLine(name + "'s power level: " + power);

		/* Everything between /* and */ becomes a comment.
		   Use this when you need to write a long, multi-line explanation.
		   Note that /* cannot be nested, so you cannot write /* inside a block comment. */

		// Block comments are also commonly used to temporarily disable code.
		/* Disabling the following line during debugging.
		Console.WriteLine("Debug output: " + power);
		*/

		// C# is a statically typed language, so types are clear from declarations.
		// Write "why" something is done rather than "what" it does — that's more valuable.

		// Using var lets the compiler infer the type. Add a comment when the type is not obvious.
		var multiplier = 50; // Transformation multiplier for Super Saiyan form.
		var ssjPower = power * multiplier;
		Console.WriteLine("Super Saiyan power level: " + ssjPower);
	}
}

The following example demonstrates this:

dotnet script CommentBasic.cs
Goku's power level: 9000
Super Saiyan power level: 450000

XmlDocComment.cs

A sample that documents a class and its methods using XML documentation comments.

using System;

/// <summary>
/// Represents a fighter character.
/// Manages the name, power level, and race, and can calculate the power after transformation.
/// </summary>
class Fighter {

	/// <summary>The character's name.</summary>
	public string Name { get; }

	/// <summary>The base power level before any transformation.</summary>
	public int BasePower { get; }

	/// <summary>The character's race (e.g., Saiyan, Namekian).</summary>
	public string Race { get; }

	/// <summary>
	/// Initializes a new instance of the Fighter class.
	/// </summary>
	/// <param name="name">The character's name.</param>
	/// <param name="basePower">The base power level before transformation. Must be 0 or greater.</param>
	/// <param name="race">The character's race.</param>
	public Fighter(string name, int basePower, string race) {
		Name = name;
		BasePower = basePower;
		Race = race;
	}

	/// <summary>
	/// </summary>
	/// <param name="multiplier">
	/// The transformation multiplier. Must be greater than 1.
	/// Example: Super Saiyan is 50, Super Saiyan 2 is 100.
	/// </param>
	/// <returns>The transformed power level (BasePower x multiplier).</returns>
	/// <remarks>
	/// Behavior is undefined if a value of 0 or less is passed.
	/// </remarks>
	public int GetTransformedPower(int multiplier) {
		return BasePower * multiplier; // Multiply the base power by the transformation factor.
	}

	/// <summary>
	/// </summary>
	/// <returns>A string in the format "Name (Race): Power XXXX".</returns>
	public string GetInfo() {
		return Name + " (" + Race + "): Power " + BasePower;
	}
}

class XmlDocComment {
	static void Main() {

		// Create instances of the Fighter class.
		// In an IDE, parameter descriptions appear as tooltips when you type new Fighter(.
		var goku = new Fighter("Goku", 9000, "Saiyan");
		var vegeta = new Fighter("Vegeta", 8000, "Saiyan");
		var piccolo = new Fighter("Piccolo", 3500, "Namekian");

		// Hover over GetInfo() in an IDE to see the <summary> content.
		Console.WriteLine(goku.GetInfo());
		Console.WriteLine(vegeta.GetInfo());
		Console.WriteLine(piccolo.GetInfo());

		Console.WriteLine();

		// Hover over GetTransformedPower in an IDE to see parameter and return value descriptions.
		int ssjMultiplier = 50; // Transformation multiplier for Super Saiyan.
		int ssj2Multiplier = 100; // Transformation multiplier for Super Saiyan 2.

		Console.WriteLine(goku.Name + " Super Saiyan: Power "
			+ goku.GetTransformedPower(ssjMultiplier));
		Console.WriteLine(vegeta.Name + " Super Saiyan 2: Power "
			+ vegeta.GetTransformedPower(ssj2Multiplier));
	}
}

Run the following command:

dotnet script XmlDocComment.cs
Goku (Saiyan): Power 9000
Vegeta (Saiyan): Power 8000
Piccolo (Namekian): Power 3500

Goku Super Saiyan: Power 450000
Vegeta Super Saiyan 2: Power 800000

Nesting block comments

C# block comments (/* */) cannot be nested. A /* inside a block comment is ignored, and the comment ends at the first */ encountered. When commenting out a large block of code that already contains a block comment, a compile error will occur.

/* Outer comment starts
   /* Inner comment (nesting not allowed) */
   This line is treated as code and causes a compile error.
*/

To avoid this, use // for commenting out code, or use the IDE's block comment feature (select multiple lines and press Ctrl+/ or equivalent).

Adding XML documentation comments to private members

XML documentation comments (///) are parsed by the compiler to generate documentation XML, but by default only public and protected members are included in the output. While /// comments on private members do appear in IDE tooltips, they are not included in the external documentation. For internal private methods, a regular // comment is often sufficient.

C# has three types of comments. // is the most commonly used single-line comment. /* */ lets you comment out an entire block, but be aware that nesting is not allowed. XML documentation comments with /// are displayed as tooltips by IDEs such as Visual Studio and Rider, so they are generally recommended for public APIs (public classes, methods, and properties).

In XML documentation comments, <summary> is the most essential tag. For methods with parameters, adding <param>, and for methods with return values, adding <returns> completes the documentation. This makes descriptions appear in IDE completion suggestions and improves team development efficiency.

Since C# is a statically typed language, the type is already visible in the declaration. Comments like // this is an int variable tend to overlap with the declaration. Comments that capture the intent — why a value is what it is, or why a certain operation is needed — add information that the code itself does not show. In cases where var is used and the type is not immediately obvious, a comment can be a useful supplement.