{"title":"Comments","description":null,"content":"Comments are notes the compiler strips out before it ever generates code. C++ gives you two real syntaxes, `//` and `/* ... */`, plus a documentation convention on top of those that tools like Doxygen read. This lesson covers each form, the rules that trip people up (especially the no-nesting rule for block comments), and the habits that keep comments useful instead of letting them rot.\n\n---\n\n# The Two Comment Syntaxes\n\nC++ has exactly two comment syntaxes built into the language: single-line and multi-line. Everything else, including doc comments, is built on top of these two.\n\n\n```cpp\n#include \n\nint main() {\n // Single-line: from // to end of line\n double price = 24.99;\n\n /*\n Multi-line: from slash-star\n to star-slash, any number of lines.\n */\n int quantity = 3;\n\n std::cout << \"Subtotal: $\" << price * quantity << std::endl;\n return 0;\n}\n```\n\n\nThe compiler removes every comment during translation, so they have zero runtime cost. The two syntaxes do the same job, just at different scales. Here's the quick reference:\n\n\n| Style | Syntax | Spans | Used For |\n| ----------- | ----------------- | ---------- | ----------------------------------------------------------------- |\n| Single-line | `// note` | One line | Short notes, trailing remarks on a code line |\n| Multi-line | `/* note */` | Many lines | Longer blocks, file headers, sometimes inline inside expressions |\n| Doc-style | `///` or `/** */` | Either | API documentation read by tools like Doxygen |\n\n\nThe rest of the lesson walks through each style, then looks at the bigger question: when comments actually help and when they get in the way.\n\n---\n\n# Single-Line Comments\n\nA single-line comment starts with `//` and runs to the end of the line. The newline closes it. Anything after `//` on that line is ignored by the compiler.\n\n\n```cpp\n#include \n\nint main() {\n // Loyalty bonus discount: 10% off for repeat customers\n double cartTotal = 89.97;\n double discounted = cartTotal * 0.90; // apply the 10% off\n\n std::cout << \"You pay: $\" << discounted << std::endl;\n return 0;\n}\n```\n\n\nTwo placements show up here. The first comment sits on its own line above the code it describes. The second is a trailing comment, tacked onto the end of a code statement. Both are fine, and both stop at the newline.\n\nA few things to remember:\n\n- `//` does not extend across lines. Each new line needs its own `//` if you're writing a multi-line note this way.\n- A trailing comment after code is still parsed correctly. The compiler reads the statement, sees `//`, and ignores the rest of the line.\n- `//` was originally a C++ feature. C didn't get `//` until C99, so older C code only used `/* ... */`. In modern C++ code, `//` is the more common choice.\n\n---\n\n# Multi-Line Comments\n\nA multi-line comment, also called a block comment, starts with `/*` and continues until the matching `*/`. The compiler treats everything between those markers as whitespace, including newlines.\n\n\n```cpp\n#include \n\nint main() {\n /*\n This program prints a tiny order summary.\n It hard-codes one product for now. Later we'll\n read the catalog from a file.\n */\n std::string productName = \"Wireless Headphones\";\n double price = 79.99;\n\n std::cout << productName << \" - $\" << price << std::endl;\n return 0;\n}\n```\n\n\nYou'll often see a `*` lined up on every line of a block comment. That's purely cosmetic. The compiler only looks at the opening `/*` and the closing `*/`. Both of these are equivalent:\n\n\n```cpp\n/*\n * File: cart.cpp\n * Purpose: Holds items added by a customer\n */\n\n/*\n File: cart.cpp\n Purpose: Holds items added by a customer\n */\n```\n\n\nBlock comments can also appear inside an expression, which `//` can't do. This is occasionally useful for inline notes about a single argument:\n\n\n```cpp\ndouble finalPrice = applyTax(basePrice, /*taxRate=*/0.08);\n```\n\n\nThe `/*taxRate=*/` block is a labeled-argument hint to readers, telling them what the `0.08` means. It doesn't change behavior, but it makes the call site easier to skim. Modern alternatives (named struct fields, designated initializers) are usually cleaner, but you'll see this pattern in older codebases.\n\n### Multi-Line Comments Don't Nest\n\nHere's the rule that catches most people off guard: block comments do not nest. The compiler matches the first `*/` it finds against the opening `/*` and treats anything after that as code.\n\n**What's wrong with this code?**\n\n\n```cpp\n#include \n\nint main() {\n /*\n Outer comment opens here.\n /* Inner comment opens here. */\n Outer was supposed to close here. */\n std::cout << \"done\" << std::endl;\n return 0;\n}\n```\n\n\nThe compiler reads the first `/*` as opening a comment, then closes that comment at the first `*/`, right after \"Inner comment opens here.\" Everything after that is code, so \"Outer was supposed to close here.\" becomes a syntax error, and the trailing `*/` is a stray token. `g++` reports something like:\n\n\n```shell\nnested.cpp:7:48: error: expected unqualified-id before '/' token\n 7 | Outer was supposed to close here. */\n | ^\n```\n\n\n**Fix:** Don't nest. Use a single block, or comment line by line with `//`:\n\n\n```cpp\n#include \n\nint main() {\n /*\n Outer comment with all the notes in one block.\n No nested /* */ inside.\n */\n std::cout << \"done\" << std::endl;\n return 0;\n}\n```\n\n\nMost editors and IDEs map a keyboard shortcut to \"toggle line comment\", which prepends `//` to every selected line. That sidesteps the nesting problem entirely.\n\n---\n\n# Commenting Out Code That Already Has `/* */`\n\nThe no-nesting rule creates a real problem: how do you temporarily disable a block of code that already contains a `/* */` comment? Wrapping it in another `/* */` won't work, because the inner `*/` closes the outer comment early.\n\nThere are two practical ways out.\n\n**Option 1:** Use `//` on every line. This always works because line comments don't have an \"opening\" and \"closing\" pair to clash with anything inside.\n\n\n```cpp\n// double calculatePremiumDiscount(double price) {\n// /* Premium customers get a flat 15% off, per the\n// 2024 loyalty program rules. */\n// return price * 0.85;\n// }\n```\n\n\n**Option 2:** Use the preprocessor's `#if 0 ... #endif`. This is the cleaner trick when the disabled block is large or already contains block comments. The preprocessor strips out everything between `#if 0` and `#endif` before the compiler sees it, and block comments inside don't matter at all.\n\n\n```cpp\n#include \n\nint main() {\n#if 0\n double calculatePremiumDiscount(double price) {\n /* Premium customers get a flat 15% off, per the\n 2024 loyalty program rules. */\n return price * 0.85;\n }\n#endif\n\n std::cout << \"Discount logic disabled for now.\" << std::endl;\n return 0;\n}\n```\n\n\nThe `#if 0` directive evaluates to false, so the preprocessor removes the guarded region entirely. The compiler never sees the disabled code, including any `/* ... */` comments inside it. To re-enable the code later, change `#if 0` to `#if 1`.\n\nThis is a sharp tool, not an everyday one. We cover preprocessor directives properly in the Namespaces & Preprocessor section. For now, treat `#if 0 ... #endif` as the escape hatch when normal comment syntax can't handle the job.\n\n---\n\n# Doc-Style Comments\n\nC++ doesn't have a built-in documentation generator the way some languages do. Instead, there's a convention: write comments in a special format above a function, class, or variable, and run an external tool that reads them and produces HTML or PDF docs. The de-facto standard tool is **Doxygen**, and the conventions it understands have become the unofficial C++ doc-comment style.\n\nDoxygen accepts two comment shapes:\n\n\n```cpp\n/// Single-line doc comment using triple-slash.\n/// Each line that starts with /// is part of the doc block.\n\n/**\n * Block-style doc comment using slash-star-star.\n * Multiple lines, often with a leading * on each one.\n */\n```\n\n\nBoth forms attach to whatever declaration comes right after them. Here's a documented `calculateShipping` function:\n\n\n```cpp\n#include \n\n/**\n * @brief Calculates the shipping cost for an order.\n *\n * Shipping is a flat base rate plus a per-kilogram weight fee plus a\n * surcharge for zones beyond the local zone. See the 2024 shipping\n * policy doc XYZ for the exact rates.\n *\n * @param weightKg package weight in kilograms, must be non-negative\n * @param zoneNumber delivery zone, 1 means local, higher numbers are farther away\n * @return shipping cost in USD\n * @note Zone 1 has no zone surcharge.\n */\ndouble calculateShipping(double weightKg, int zoneNumber) {\n const double baseCost = 5.0;\n const double perKgFee = 2.0;\n const double zoneFee = 3.0;\n return baseCost + (weightKg * perKgFee) + ((zoneNumber - 1) * zoneFee);\n}\n\nint main() {\n std::cout << \"Shipping for 2.5kg to zone 3: $\"\n << calculateShipping(2.5, 3) << std::endl;\n return 0;\n}\n```\n\n\nThe text inside the `/** ... */` block does two jobs at once. To a human reading the source, it describes what `calculateShipping` does and what each parameter means. To Doxygen, the `@` tags pull out structured information that becomes a function reference page in the generated HTML.\n\nThe common tags you'll see:\n\n\n| Tag | Used On | Meaning |\n| ---------- | ------------------ | --------------------------------------------------------- |\n| `@brief` | Any element | One-line summary, shown in lists and indexes |\n| `@param` | Functions, methods | Describes one parameter (one tag per parameter) |\n| `@return` | Functions, methods | Describes the return value |\n| `@note` | Any element | Highlighted note or caveat |\n| `@throws` or `@exception` | Functions, methods | An exception the function may throw |\n| `@see` | Any element | Cross-reference to a related symbol |\n| `@deprecated` | Any element | Marks the element as discouraged, with a reason |\n\n\nYou don't need to install Doxygen to write doc comments. They're still useful as in-source documentation, and the format is consistent enough that anyone reading your code recognizes it. When the project later decides to publish API docs, the comments are already in the right shape.\n\nThis is a brief intro, not a Doxygen tutorial. The tool has dozens of tags, configuration options, and output formats. If your team uses it, the project will have a `Doxyfile` and conventions to follow.\n\n---\n\n# When Comments Help and When They Hurt\n\nThe hardest part of writing comments isn't the syntax, it's deciding what to write. The single most useful rule is this: **explain WHY, not WHAT**. The code already tells the reader what it does. A comment should explain things the code can't.\n\nCompare these two versions of the same function:\n\n\n```cpp\n#include \n\n// Noise comments: tell you nothing the code doesn't already say\ndouble getTotalNoise(double subtotal, double taxRate) {\n // multiply subtotal by 1 plus taxRate\n double raw = subtotal * (1 + taxRate);\n // round raw times 100 then divide by 100\n return static_cast(raw * 100 + 0.5) / 100.0;\n}\n\n// Useful comment: explains the non-obvious decision\ndouble getTotalGood(double subtotal, double taxRate) {\n double raw = subtotal * (1 + taxRate);\n // Round to cents using half-up so totals match what\n // the finance team prints on paper invoices.\n return static_cast(raw * 100 + 0.5) / 100.0;\n}\n\nint main() {\n std::cout << \"Total: $\" << getTotalGood(89.97, 0.08) << std::endl;\n return 0;\n}\n```\n\n\nThe first version's comments restate the operators. Any reader can see `subtotal * (1 + taxRate)`, so \"multiply subtotal by 1 plus taxRate\" is filler. The second version explains *why*: the rounding mode matches a business expectation. That information doesn't appear anywhere in the code.\n\nUseful comments tend to cover:\n\n- **Why a decision was made.** \"We round half-up because that matches paper invoices.\"\n- **Surprising constraints.** \"Quantity zero is allowed for placeholder items in promotions.\"\n- **Business or regulatory rules.** \"10% loyalty bonus per company policy doc XYZ.\"\n- **Workarounds.** \"Old orders have empty shipping addresses; treat empty as 'pickup in store'.\"\n- **Pointers to context.** Links to a bug ticket, a spec section, or a related commit.\n- **Non-obvious algorithms.** When the implementation uses a trick that isn't self-explanatory.\n\nComments that hurt more than they help:\n\n- **Restating the code.** `// increment count` above `count++`.\n- **Stale comments.** A comment that described the old behavior and never got updated. Now it lies.\n- **Commented-out dead code.** Old logic left behind \"just in case\".\n- **TODO / FIXME without owner or context.** \"TODO: fix this\" with no name and no date.\n- **Decorative banners.** `// ====== SECTION ======`. Blank lines and good function names work better.\n\n\n> **INFO**\n>\n> **Cost:** Comments are free at runtime, but they cost reader trust. A wrong comment is worse than no comment because readers waste time reconciling code with a description that drifted.\n\n\n---\n\n# What's Wrong With This Code?\n\n\n```cpp\n#include \n\ndouble applyLoyaltyDiscount(double price) {\n /* Old logic from before the 2023 redesign.\n Kept here in case product wants to roll back.\n\n double bonusRate = 0.05;\n double bonus = price * bonusRate;\n return price - bonus;\n */\n\n // 10% loyalty bonus per company policy doc XYZ\n return price * 0.90;\n}\n\nint main() {\n std::cout << \"$\" << applyLoyaltyDiscount(100.0) << std::endl;\n return 0;\n}\n```\n\n\nThe function works, but the commented-out block at the top is dead weight. It clutters the file, drifts further out of sync every time the surrounding code changes, and offers nothing a reader can act on. The \"in case product wants to roll back\" comfort is illusory: nobody is going to come back six months later, find this block, and trust it as a reliable rollback path.\n\n**Fix:** Delete the dead code. Version control remembers every line you've ever committed, so the history is already preserved in `git log` and `git blame`:\n\n\n```cpp\n#include \n\ndouble applyLoyaltyDiscount(double price) {\n // 10% loyalty bonus per company policy doc XYZ\n return price * 0.90;\n}\n\nint main() {\n std::cout << \"$\" << applyLoyaltyDiscount(100.0) << std::endl;\n return 0;\n}\n```\n\n\nIf you genuinely need a record of the old behavior alongside the new, write a short comment that explains what changed and link to the commit or ticket. That's far more useful than a copy of the code itself.\n\n---\n\n# TODO and FIXME Hygiene\n\n`TODO` and `FIXME` markers are useful when they carry enough information for someone other than the author to act on them. A bare `// TODO: fix this` tells the next reader nothing. A good marker includes who's responsible (or at least who wrote it), what needs to happen, and ideally a ticket link.\n\n\n```cpp\n// TODO(priya, ECOM-4521): switch to the v2 pricing service once it ships in Q3.\n// v2 returns prices in cents instead of dollars, so callers must divide by 100.\ndouble getCurrentPrice(int productId) {\n return legacyPricingService.fetchPrice(productId);\n}\n```\n\n\nThat marker survives the original author leaving the team, because the ticket carries the context. A `// FIXME` follows the same pattern but signals something actively broken, not just a future improvement.\n\nA handful of guidelines that keep these markers useful:\n\n- Include a name or ticket so it doesn't become anonymous.\n- Say what needs to happen and why, not just \"this is bad\".\n- Treat them as debt to pay down, not permanent decoration.\n- Periodically grep for them and either fix them or convert them to real tickets.\n\n---\n\n# Self-Documenting Code\n\nThe best comment is often no comment at all, replaced by a name that makes the code obvious on its own. If you find yourself reaching for a comment to clarify what a variable or function does, ask first whether a better name would do the same job:\n\n\n```cpp\n#include \n\n// Before: a comment compensates for an opaque name\nint adj(int x, int y) {\n // x is current stock, y is units sold today\n return x - y;\n}\n\n// After: clear names, comment not needed\nint remainingStock(int currentStock, int unitsSold) {\n return currentStock - unitsSold;\n}\n\nint main() {\n std::cout << \"Stock left: \" << remainingStock(20, 7) << std::endl;\n return 0;\n}\n```\n\n\n`remainingStock(currentStock, unitsSold)` reads like English. There's nothing left for a comment to clarify. Save comments for things names can't carry: the *why*, the constraints, the surprising rules.\n\nSmall functions help too. A 200-line function needs comments to break it into chunks. A 15-line function with a good name doesn't need section headers because the name already says what it does.\n\n---\n\n# Style and Consistency\n\nC++ doesn't have a single official rule about whether to use `//` or `/* ... */` for ordinary comments. Both are valid. The choice is mostly about code review and consistency within a codebase, not technical correctness. Most modern C++ codebases prefer `//` for everyday comments because:\n\n- It can't be accidentally left unclosed (no missing `*/`).\n- It plays well with editors that toggle line comments on selection.\n- It avoids the no-nesting problem when you want to disable a block of code.\n\n`/* ... */` still shows up for file headers, long block comments, and inline-in-expression notes. Doc comments use `///` or `/** ... */` depending on team convention.\n\nThe right answer is whatever your project already does. If you join a team and every file uses `/* ... */` block headers, write block headers. If they use `//`, use `//`. Consistency matters more than the choice itself.\n\n---\n\n# Comment Hygiene\n\nA few habits keep comments from rotting:\n\n- **Keep comments next to the code they describe.** A comment 30 lines above its target is easy to miss when one of them changes.\n- **Update comments when the code changes.** Treat the comment as part of the change, not a side note. A stale comment is a bug.\n- **Prefer good names over explanatory comments.** If a comment is restating intent, the names need work.\n- **Don't apologize.** \"Sorry, this is messy\" doesn't fix anything. Either clean it up or document the constraint that forced it.\n- **Doc-comment public APIs.** Things other developers will call (public functions, classes, headers) deserve `///` or `/** */`. Private helpers rarely do.\n- **Delete dead code instead of commenting it out.** Trust your version control history.\n\n---\n\n# Summary\n\n- C++ has two comment syntaxes: single-line `//` (ends at newline) and multi-line `/* ... */` (ends at the first `*/`). Both are stripped by the compiler and cost nothing at runtime.\n- Block comments do not nest. The first `*/` always closes the comment that the first `/*` opened. To disable code containing block comments, use `//` line by line or wrap it in `#if 0 ... #endif`.\n- Doc-style comments (`///` or `/** ... */`) aren't a separate language feature. They're a convention that tools like Doxygen read to generate API documentation. Common tags include `@brief`, `@param`, `@return`, and `@note`.\n- Good comments explain *why*: business rules, design decisions, surprising constraints, links to specs or tickets. Bad comments restate the code, drift out of date, or sit as dead commented-out blocks.\n- Self-documenting code beats most comments. Clear names and small functions remove the need for explanatory notes. Save comments for things names can't carry.\n- TODO and FIXME markers are useful only when they include a name (or ticket), a concrete action, and enough context for someone else to act on them.\n- Choosing between `//` and `/* */` for ordinary comments is mostly a style decision, not a technical one. Match what your project already does; consistency matters more than the choice itself.\n\nIn the next lesson, we'll move from describing code with comments to choosing the names themselves: the conventions C++ developers follow for variables, functions, classes, and constants, and why those conventions make code easier to read at a glance.","pageType":"cpp"}

Comments

Get Premium