C# Comments and Readable Code

What you will be able to do

• Recognize single-line and block comments and their boundaries.
• Distinguish comment markers from the same characters inside strings.
• Explain a decision or assumption without repeating obvious code.
• Improve names and layout while preserving behavior.
• Detect comments that disagree with the implementation.
• Check a readability change using predicted results and changed inputs.

Write for the next reader, including your future self

You can understand a program today because you remember why you wrote it. Another reader does not have that memory. Readable code carries enough meaning in its names, structure and explanations that someone can follow the rule without asking its author to translate every line.

A comment is source text intended for readers rather than an instruction to the running application. It can explain why a decision was made or what a small example deliberately leaves out. It cannot make an incorrect expression correct or enforce an input rule just by describing one.

Use the console programs from previous lessons as your starting point. You already know declarations, simple arithmetic and labelled output; this lesson improves how those ideas are communicated in the source. Each example is a separate complete Program.cs, and the expected output remains a reference to compare with an actual run.

using System;

int sessionMinutes = 45;
// Reserve a short break instead of filling the entire session with practice.
int breakMinutes = 5;
int practiceMinutes = sessionMinutes - breakMinutes;

Console.WriteLine($"Practice minutes: {practiceMinutes}");

Select Run code to compile and execute this program.

Practice minutes: 40

Know exactly where a comment starts and ends

A single-line comment starts with // outside a string and continues to the end of that physical source line. It can occupy a line of its own or follow a complete statement. A block comment starts with /* and finishes at the first following */. It can span several lines, or appear within one line.

Read the punctuation before moving code. A semicolon placed inside a single-line comment does not terminate the statement before it. If you move active code onto the end of a // line, that code becomes part of the comment. Formatting is usually about presentation, but changing these line boundaries can change what source remains active.

Use a block for a cohesive note that genuinely needs several lines. Use a short preceding line comment for a brief explanation. Neither form is a license to write a paragraph for every simple assignment. In the following report, the note explains which inputs the example assumes rather than promising that it validates those inputs.

using System;

/*
   This report uses whole minutes supplied in the source.
   Assume completed minutes are between zero and the planned total.
   Input validation is not part of this example.
*/
int plannedMinutes = 45;
int completedMinutes = 20;
Console.WriteLine($"Minutes left: {plannedMinutes - completedMinutes}");

Select Run code to compile and execute this program.

Minutes left: 25

using System;

int reservedMinutes = 5; // A break is included in this plan.
int availableMinutes = 45 - reservedMinutes;
Console.WriteLine($"Available: {availableMinutes}");

Select Run code to compile and execute this program.

Available: 40

A URL or quoted marker is not a source comment

The previous output lesson showed that quoted characters are data. The same rule matters here: // inside an ordinary string is part of the message, not the beginning of a comment. A URL can therefore contain slashes without hiding the rest of the call.

Before deciding that text is commented out, find the surrounding quote boundaries and any escape sequences. Syntax highlighting can help, but the actual boundaries are determined by the language. Do not repair a valid URL by deleting its slashes or adding comment markers elsewhere.

Run the next program, then change only the note text inside the second message. Its output should change. Contrast that with changing explanatory text in a real source comment, which does not itself print anything. This experiment distinguishes what the program displays from what a developer reads in the source.

using System;

Console.WriteLine("Reference: https://sovrancode.org");
Console.WriteLine("Markers: /* note */ and // note");

Select Run code to compile and execute this program.

Reference: https://sovrancode.org
Markers: /* note */ and // note

Commenting out code is a source change

Sometimes you disable one diagnostic message while investigating a program. A line comment can do that without deleting the text. Predict which calls remain active, then run the example. Restoring the disabled call changes the output because you restored an instruction, not because the comment became executable.

Keep these experiments small and reversible. If you disable a declaration while leaving later references, the source can stop compiling. If you disable a check in a larger application, the program's behavior can change. Commenting out code is not automatically a harmless readability edit.

When an experiment ends, keep the useful final version and remove distracting disabled alternatives. An existing repository's version history can preserve earlier versions. A TODO note can record a concrete remaining task, but it does not complete that task and should not be mistaken for a working feature.

using System;

Console.WriteLine("Starting practice");
// Console.WriteLine("Diagnostic: reached the report");
Console.WriteLine("Practice complete");

Select Run code to compile and execute this program.

Starting practice
Practice complete

using System;

// int plannedMinutes = 45;
Console.WriteLine(plannedMinutes);

Select Run code to compile and execute this program.

Compilation fails: plannedMinutes has no active declaration.

Improve the code before explaining around it

Start with names that reveal the roles of values. plannedMinutes and completedMinutes let a reader inspect the subtraction directly. A comment explaining that a means planned minutes is a weaker solution when you are free to choose a clearer name.

Group declarations, the calculation and the output into recognizable steps. Use one statement per line, spaces around operators and consistent indentation within blocks. Blank lines can separate related work. These are readability conventions, not proof that the rule is correct; preserve string content, operators and statement order while changing layout.

Compare the compact program with the improved version. First confirm the same original output. Then change the planned and completed values in both and compare again. A single matching result is easy to obtain accidentally; changed inputs provide stronger evidence that you preserved the relationship rather than copied the answer.

using System;
int a=45;int b=20;Console.WriteLine($"Minutes left: {a-b}");

Select Run code to compile and execute this program.

Minutes left: 25

using System;

int plannedMinutes = 45;
int completedMinutes = 20;

// This simple report assumes the supplied progress is within the plan.
int remainingMinutes = plannedMinutes - completedMinutes;

Console.WriteLine($"Minutes left: {remainingMinutes}");

Select Run code to compile and execute this program.

Minutes left: 25

Explain decisions and limitations, not obvious syntax

A comment saying declare an integer beside an int declaration repeats what the language already shows. A note explaining that the plan reserves a break adds the reason behind a chosen value. A note explaining that this beginner report does not validate its inputs makes the example's limits clear.

Keep comments specific enough to check. This report assumes zero to total pages is more useful than this code is safe. If the requirement changes, reread the nearby comments as well as the expression. A stale explanation can mislead a reviewer precisely because it sounds confident and familiar.

Code and prose can disagree in either direction. Decide what the requirement actually is, predict the right result, and inspect the implementation. If the requirement calls for subtraction and the code adds, fix the rule. Do not simply change the comment to say addition so the disagreement disappears on paper.

Close block comments and avoid nesting them

An unfinished block comment is a compilation error, even if there is a valid output call earlier in the file. Compilation happens before this program runs. The earlier call is not executed first as a reward for appearing before the mistake.

Block comments do not nest. When the compiler encounters the first closing marker, that comment ends. An inner-looking opening marker does not make the compiler wait for an additional closing marker. This is why wrapping an existing commented region in another block can expose text you intended to hide.

Use one block with plain text inside, or use separate // lines for a longer note. After repairing the boundary, run the program and check which calls are active. A repaired delimiter can make a previously hidden call active again, so compilation success is only the first part of the check.

using System;

Console.WriteLine("Ready");
/* Explain the report below.
Console.WriteLine("Report complete");

Select Run code to compile and execute this program.

Compilation fails because the block comment never closes.

using System;

/* Outer note begins.
   /* Inner note ends here. */
   This text was intended to remain a comment.
*/
Console.WriteLine("Ready");

Select Run code to compile and execute this program.

Compilation fails: the first closing marker already ended the block comment.

Recognize documentation comments without overusing them

You may see triple-slash comments, written as ///, above types and members in other projects. These are XML documentation comments: tools can use their structured content to provide API documentation. They serve a different purpose from a short note beside a calculation.

You do not need to add XML documentation above every top-level statement in this lesson. Later, when you design methods and classes, descriptions of parameters, results and assumptions can help callers use those APIs. Today, focus on accurate ordinary comments and code that is readable without a large annotation layer.

Treat comments as part of the review, not a substitute for running the code. The checklist below asks whether the names are clear, the explanation adds missing context, the claim is supported and the edit preserves the behavior it promises to preserve.

A small review checklist

Does a name already explain this?

Prefer a useful name such as pagesRead over a vague name plus a comment saying what it stores. Rename its references consistently; changing only a comment does not rename code.

What information would a reader otherwise miss?

Explain a decision, an assumption, a limitation or a necessary workaround. A comment saying add two values beside an addition rarely adds anything the expression did not already say.

Does the source actually support the claim?

Read the code and try changed inputs. A comment saying validated, saved or secure does not implement validation, persistence or security.

What should remain unchanged?

For a readability-only edit, record the intended result and compare before and after. If you also fix a rule, identify that behavior change explicitly rather than presenting it as formatting.

Guided repair: when the comment and the code disagree

A report must show planned minutes minus completed minutes. Read the reassuring comment, predict the required 25, then run the original. Repair the calculation and replace the repetitive comment with an accurate limitation. Describe this as a behavior repair rather than a formatting-only change.

using System;

int plannedMinutes = 45;
int completedMinutes = 20;
// Subtract completed work from the planned session.
int remainingMinutes = plannedMinutes + completedMinutes;
Console.WriteLine($"Minutes left: {remainingMinutes}");

Select Run code to compile and execute this program.

Minutes left: 65

Repair checkpoints

1. The original source compiles and prints 65, which contradicts the required rule.
2. Use subtraction so the original inputs produce 25.
3. Keep the label Minutes left unchanged.
4. With completedMinutes = 0, expect 45; with 45, expect 0.
5. With completedMinutes = 50, expect -5 and explain that no input validation exists.

using System;

int plannedMinutes = 45;
int completedMinutes = 20;

// Input is fixed here; this version does not reject progress beyond the plan.
int remainingMinutes = plannedMinutes - completedMinutes;
Console.WriteLine($"Minutes left: {remainingMinutes}");

Select Run code to compile and execute this program.

Minutes left: 25

Independent lab: improve readability without changing the result

Improve a working reading report without changing its behavior. The goal is for another student to understand the values, calculation and limitation without needing you to explain the source aloud.

Acceptance checklist

• Rename x to totalPages and y to pagesRead, updating every active reference.
• Put one statement per line and group inputs, calculation and output.
• Remove comments that merely restate declarations or assignments.
• Replace the unsupported safety claim with a precise assumption or limitation.
• Preserve the subtraction and the exact output label Pages left: .
• For the original 80 and 25 inputs, keep the result 55; do not hardcode it.

using System;
// This is an integer.
int x=80;int y=25; // Set y.
// Makes reading progress safe.
Console.WriteLine($"Pages left: {x-y}");

Select Run code to compile and execute this program.

Pages left: 55

using System;

int totalPages = 80;
int pagesRead = 25;

// This report assumes progress is within the book; it does not validate it.
int remainingPages = totalPages - pagesRead;

Console.WriteLine($"Pages left: {remainingPages}");

Select Run code to compile and execute this program.

Pages left: 55

Compare before and after

• Zero pages read: total 80 and read 0 must leave 80.
• Finished book: total 80 and read 80 must leave 0.
• Progress beyond the book: total 80 and read 90 produces -10 in both versions.
• Different book: total 120 and read 30 must leave 90.
• Read your final comment alongside the negative case. It must not claim that the program rejects it.

Frequently asked questions

Recap and next step

Use names and layout to expose the calculation. Use comments to explain a reason, assumption or limitation. Read comment boundaries carefully, keep explanations in sync with the source, and compare before-and-after behavior when improving readability.

This completes the first unit’s published lessons. Next is C# Variables and Constants, where you will follow stored values and assignments in more detail. Keep the reading report: its clear names make it a useful starting point for that work.

Official references

Original SovranCode explanations and exercises. Language rules and style guidance were checked against the references below.

• Microsoft Learn: Comment syntax
• Microsoft Learn: C# coding conventions

Last updated: 26 October 2026.