Comments: explaining intent in C
Understand comment syntax, translation, limitations, and the difference between documenting a decision and changing program behavior.
In this chapter8 sections
Comments explain the source to people reading it. They can record why a choice was made or what an operation assumes. They also have syntax rules, so we will learn where comments start, where they stop, and how they affect the surrounding text.
1. C has two familiar comment forms
/* A block comment can span
more than one source line. */
int count = 3;
// One more book has just arrived.
count += 1;A block comment starts with /* and ends at the first following */. A line comment starts with // and runs to the end of the relevant source line after line splicing. Line comments are available from C99 onward, including our C17 baseline. A block comment can fit on one line too.
The code performs the increment. The comment explains why. If the comment says “one more arrived” but the code subtracts one, the comment does not change the operation. Check comments against both the code and the intended task.
2. Comments are replaced, not pasted away
During translation, each comment is replaced by a space. That preserves separation in int/**/count. Deleting the comment without the replacement space would produce intcount, a different token. A comment adds no executed operation, but its position can affect how source tokens are separated.
Comment syntax is recognized according to lexical context. The characters // inside a string literal do not start a line comment, and /* in a string does not start a block comment. This distinction is useful for URLs and text that itself contains source-code punctuation.
#include <stdio.h>
int main(void) {
puts("/* this is text */");
return 0;
}If the output succeeds, the program writes the apparent comment markers as ordinary text, followed by a newline. The quotation marks establish a string literal; the markers are part of its data. Do not reason about comments by searching for their two characters without considering where those characters occur.
3. Block comments do not nest
Block comments do not nest. An inner /* does not create another level; the first */ ends the comment. Be careful when wrapping existing source in a block comment. An existing closing marker can end it early and expose source you meant to exclude.
For temporarily excluding source, use an editor’s line-comment tool carefully or a suitable conditional-preprocessing technique when you understand its rules. Do not treat either as a substitute for a deliberate code change and a review. “Commented out” is not automatically a safe description of an arbitrary pasted region.
4. Physical lines and logical lines can differ
C joins a backslash immediately followed by a newline before replacing comments. As a result, a // comment can continue onto the next physical line. Avoid putting such a backslash at the end of a line comment. Indenting the next line does not cancel the joining rule.
Go deeper: removing comments is a lexical task
A tool that removes comments must account for string and character literals, escapes, line splicing, and token separation. A naive text replacement can change a program even if the original author meant only to reformat it. This is one reason language-aware tooling is useful.
5. Document the reason and the boundary
A useful comment explains a decision: the unit of a measurement, an allowed range, or why two steps must occur in order. Use names to make ordinary operations readable. Use comments for the reason or assumption that a reader could not easily recover from the code.
Comments can become stale. When changing code, check the explanation, assumptions, and examples that accompany it. A reassuring sentence such as “input is always valid” is not validation. Either establish that contract at the appropriate boundary or handle failure. Clear names and small, coherent functions reduce the amount of explanatory repair a comment must do.
The source contains puts("// note");. Does // prevent that call from producing output?
Read the explanation
No. It occurs inside a string literal and is ordinary string data. In a suitable complete program, a successful call writes the text and a newline.
Primary references and further reading
- WG14 N1570 — public C11 committee draft: Sections 5.1.1.2 and 6.4.9 provide the core rules used in this C17-baseline explanation. This is a public draft, not the final ISO publication.
Before you move on
- Comments explain intent without becoming ordinary executed operations.
- Comment replacement, literals, and line splicing affect how source is interpreted.
- A useful comment records a reason or contract and must stay consistent with the code.
Keep these ideas separate
- Comment marker / Literal data
- The same slash characters can be string data inside quotation marks instead of starting a comment.
Why can deleting comment characters carelessly change token boundaries or expose unintended source?
Optional: say it aloud or keep a note. You can continue whenever you are ready.Check your understanding
Optional. Answers are not saved or sent, and reading stays unrestricted.
Read the explanation for every choice
- The comment is replaced by whitespace, separating the tokens.
✓ Correct reasoning. It does not join int and count into a single identifier.
- The comment executes before the declaration.
Comments are handled during translation, not executed as runtime statements.
- The characters become the identifier intcount.
Comment replacement supplies separation instead of concatenating these tokens.
C17
Quick reference from the earlier edition
This compact reference keeps existing links and saved passages available. Read the expanded lesson above for the full context.
Comments are non-executable annotations in the source code, intended to improve readability and maintainability. The C language supports two types of comments:
- Multi-line Comments: Enclosed between
/*and*/. Everything between these delimiters is ignored by the compiler.
/* This is a multi-line comment.
It can span several lines. */
- Single-line Comments: Introduced in C99, start with
//and continue to the end of the line.
// This is a single-line comment.
Best Practices:
- Use comments to explain complex logic, assumptions, or the purpose of code sections.
- Avoid redundant comments that restate obvious code.
- Prefer comments that explain "why" rather than "how".
- Do not use comments as a substitute for clear code.
Example:
#include <stdio.h>
// Print the sum of two numbers
int main(void) {
int a = 5, b = 10;
/* Calculate and print the sum */
printf("Sum: %d\n", a + b);
return 0;
}
Note: Block comments do not nest: the first */ ends the comment. An inner /* is ordinary comment text. An attempted nested comment may leave unintended source text and cause diagnostics or change the program; it is not a supported commenting technique.
Ready for the next idea?
Mark this chapter as read whenever you feel ready.