{"title":"Comments","description":null,"content":"Comments are notes the compiler strips out before it 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 cause problems (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 at different scales. A 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 `//` for a multi-line note in this style.\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 did not 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. A later version\n reads 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\nA `*` lined up on every line of a block comment is common. It is 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 `//` cannot 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 does not change behavior, but it makes the call site easier to skim. Modern alternatives (named struct fields, designated initializers) are usually cleaner, but this pattern appears in older codebases.\n\n### Multi-Line Comments Do Not Nest\n\nOne rule worth knowing: 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 is 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:** Do not 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 `/* */` will not 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 do not 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 cleaner 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 do not 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. The Namespaces & Preprocessor section covers preprocessor directives in depth. Treat `#if 0 ... #endif` as the escape hatch when normal comment syntax cannot handle the job.\n\n---\n\n# Doc-Style Comments\n\nC++ does not have a built-in documentation generator the way some languages do. Instead, there is 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. 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\nCommon tags:\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\nInstalling Doxygen is not required to write doc comments. They are 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 is not the syntax, it is deciding what to write. The most useful rule: **explain WHY, not WHAT**. The code already tells the reader what it does. A comment should explain things the code cannot.\n\nCompare these two versions of the same function:\n\n\n```cpp\n#include \n\n// Noise comments: tell you nothing the code does not 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 does not 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 technique that is not 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\nComments cost nothing 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# What Is 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 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 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 is 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 is 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 does not 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 are writing a comment to clarify what a variable or function does, first ask 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 is nothing left for a comment to clarify. Save comments for things names cannot 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 does not need section headers because the name already says what it does.\n\n---\n\n# Style and Consistency\n\nC++ does not 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 cannot 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 disabling 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- **Do not apologize.** \"Sorry, this is messy\" does not 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.","pageType":"cpp"}

Comments

Get Premium