Comments and Documentation

Vaibhav • September 11, 2025

As your programs grow beyond a few lines, you’ll quickly realize that writing code is only half the job. The other half? Making sure it’s understandable-by others and by your future self. That’s where comments and documentation come in. In this article, we’ll explore how to write effective comments in C#, the different types of comments the language supports, and how to use XML documentation to describe your code in a way that tools like Visual Studio and IntelliSense can understand.

Why Comments Matter

Code is read far more often than it is written. What seems obvious today may be confusing tomorrow. Comments help bridge that gap. They explain why something is done, clarify complex logic, and provide context that code alone can’t always convey.

Good comments make your code easier to maintain, debug, and extend. They’re especially helpful when:

• You’re solving a tricky problem or using a workaround
• You want to explain the purpose of a line or block of code
• You’re collaborating with others (or your future self)

Single-Line Comments

The simplest way to add a comment in C# is with //. Everything after // on that line is ignored by the compiler.

// This prints a greeting to the console
Console.WriteLine("Hello, world!");

You can also place comments at the end of a line:

Console.WriteLine("Hello"); // Output a message

These are great for quick notes or reminders. They’re also useful for temporarily disabling a line of code during testing.

Multi-Line Comments

For longer explanations, or when you want to comment out a block of code, you can use multi-line comments with /* ... */.

/*
 This section handles user input.
 We'll expand it in the next chapter.
*/
Console.WriteLine("Enter your name:");

You can also use multi-line comments to temporarily disable multiple lines of code:

/*
Console.WriteLine("Line 1");
Console.WriteLine("Line 2");
*/

Be careful not to nest multi-line comments-they don’t support that. If you try to comment out a block that already contains /* ... */, you’ll get a compilation error.

XML Documentation Comments

C# also supports a special kind of comment that starts with ///. These are called XML documentation comments, and they’re used to describe classes, methods, and other members in a structured way.

Even though we haven’t introduced custom methods yet, you can still use XML comments to describe the Main method or the Program class itself.

/// <summary>
/// This is the entry point of the application.
/// </summary>
static void Main(string[] args)
{
    Console.WriteLine("Hello, world!");
}

These comments are picked up by IDEs like Visual Studio and VS Code to show tooltips and generate documentation. They’re especially useful when writing code that others will use or when working in larger teams.

When to Use Each Type

Use // for quick notes or explanations. Use /* ... */ for longer blocks or temporarily disabling code. Use /// when documenting public methods or classes that others will use.

Here’s a combined example using only the concepts we’ve introduced so far:

using System;

/// <summary>
/// The main class of the application.
/// </summary>
class Program
{
    /// <summary>
    /// The entry point of the program.
    /// </summary>
    static void Main(string[] args)
    {
        // Print a welcome message
        Console.WriteLine("Welcome to C#!");

        /*
         This is where we’ll add input handling later.
         For now, we’re just printing a message.
        */
    }
}

Notice how each type of comment serves a different purpose. The single-line comment explains a specific line. The multi-line comment provides context for a block. The XML comments describe the method and class for documentation tools.

Common Pitfalls

While comments are helpful, they can also become a liability if misused. Here are a few things to avoid:

• Outdated comments: If you change the code but forget to update the comment, it becomes misleading.
• Redundant comments: Don’t write comments that simply restate what the code already says.
• Over-commenting: Too many comments can clutter your code and make it harder to read.

The best comments are concise, relevant, and focused on explaining why something is done-not how.

Summary

In this article, you learned how to write comments and documentation in C#. You now know:

• How to use single-line (//) and multi-line (/* */) comments
• How to write XML documentation comments (///) for methods and classes
• Why comments are essential for maintainability and collaboration
• When and how to use each type of comment effectively

Clear, thoughtful comments are a hallmark of professional code. They make your programs easier to understand, easier to maintain, and easier to share. In the next article, we’ll explore how to interact with users through basic input and output.