Best Practices

You now know both kinds of comments in C#: // and /* */. But just as important as the syntax is knowing when and how to use comments effectively. Here are the most important rules for good comments.

Rule 1: Explain the WHY, not the WHAT. Good code is often already self-explanatory — what it does is visible from the code itself. A comment is usually only helpful when it explains the reasoning behind a decision.

// Bad: just repeats the code
// prints Hello
Console.WriteLine("Hello");

// Good: explains the reason
// Greeting shown the first time the app launches
Console.WriteLine("Hello");

The comment "// prints Hello" above Console.WriteLine("Hello"); is an example of a good comment.

Rule 2: Keep comments up to date. When the code changes but the comment doesn't, you end up with an outdated comment — which is often worse than no comment at all, because it misleads whoever reads it next (including future you).

// Prints the user's first name
Console.WriteLine("Welcome back!");

A comment that no longer matches the current code is called ____.

Rule 3: Don't over-comment. If every single, obvious line gets its own comment, the code becomes cluttered instead of clearer. Use comments purposefully — to mark sections or explain genuinely tricky parts. As a bonus, C# also has a special triple-slash comment (///) used to generate reference documentation for your code, which you will encounter later once you start writing your own methods.

// Bad: a comment for every single, obvious line
class Program
{
    static void Main()
    {
        // prints text
        Console.WriteLine("Hello");
    }
}

// Good: a comment marks only the important section
class Program
{
    static void Main()
    {
        // --- Greeting ---
        Console.WriteLine("Hello!");
        Console.WriteLine("Glad you're here.");
    }
}

When is a comment most useful?