C++ Comments Guide: Single-Line, Multi-Line, and Documentation Styles
What is C++ Comments Guide: Single-Line, Multi-Line, and Documentation Styles? Comments are an important part of writing readable C++ code. They allow developers to explain what code does, leave notes for future changes, document functions...
What comment types are available in C++ and how are Doxygen documentation tags structured?
Explanation & In-Depth Details
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp">#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span>
<span class="js-id">int</span> <span class="js-id">main</span><span class="js-op">()</span> <span class="js-op">{</span>
<span class="js-cm">// Print a welcome message</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"Welcome to C++"</span><span class="js-op">;</span>
<span class="js-kw">return</span> <span class="js-num">0</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>The compiler does not execute:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Print a welcome message</span></code></pre></div><p>It is only there to help people understand the code.</p><p>A simple way to think about comments is:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text"><span class="js-id">C</span><span class="js-op">++</span> <span class="js-id">Source</span> <span class="js-id">Code</span>
<span class="js-op">|</span>
<span class="js-op">+----</span> <span class="js-id">Code</span> → <span class="js-id">Compiled</span>
<span class="js-op">|</span>
<span class="js-op">+----</span> <span class="js-id">Comments</span> → <span class="js-id">Ignored</span> <span class="js-id">by</span> <span class="js-id">compiler</span></code></pre></div><p>Comments are therefore meant primarily for programmers, maintainers, reviewers, and documentation tools.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Why Are Comments Important?</h2><p>Good comments can make code easier to understand and maintain.</p><p>They are especially useful when:</p><ul data-spread="false"><li><p>Explaining complicated logic</p></li><li><p>Describing why a particular approach was chosen</p></li><li><p>Documenting functions and classes</p></li><li><p>Marking temporary work</p></li><li><p>Explaining unusual behavior</p></li><li><p>Providing information for future developers</p></li><li><p>Creating API documentation</p></li></ul><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Convert temperature from Celsius to Fahrenheit.</span>
<span class="js-id">double</span> <span class="js-id">fahrenheit</span> <span class="js-op">=</span> <span class="js-op">(</span><span class="js-id">celsius</span> <span class="js-op">*</span> <span class="js-num">9.0</span> <span class="js-op">/</span> <span class="js-num">5.0</span><span class="js-op">)</span> <span class="js-op">+</span> <span class="js-num">32.0</span><span class="js-op">;</span></code></pre></div><p>The comment gives the reader immediate context.</p><p>However, comments should not be used everywhere simply for the sake of adding comments.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Types of Comments in C++</h2><p>C++ supports two main comment syntaxes.</p><table><tbody><tr><th>Comment type</th><th>Syntax</th><th>Typical use</th></tr><tr><td>Single-line</td><td><code dir="ltr">//</code></td><td>Short explanations and notes</td></tr><tr><td>Multi-line</td><td><code dir="ltr">/* ... */</code></td><td>Longer comments or temporarily disabling code</td></tr></tbody></table><p>Documentation tools can also recognize special comment formats.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">1. Single-Line Comments in C++</h2><p>A single-line comment begins with:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">//</span></code></pre></div><p>Everything after <code dir="ltr">//</code> on that line is treated as a comment.</p><p>Example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp">#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span>
<span class="js-id">int</span> <span class="js-id">main</span><span class="js-op">()</span> <span class="js-op">{</span>
<span class="js-cm">// Display a greeting</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"Hello, C++!"</span><span class="js-op">;</span>
<span class="js-kw">return</span> <span class="js-num">0</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>The comment:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Display a greeting</span></code></pre></div><p>does not affect program execution.</p><div><hr></div><h2>Single-Line Comment After Code</h2><p>You can also put a comment after a statement:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span> <span class="js-id">age</span> <span class="js-op">=</span> <span class="js-num">25</span><span class="js-op">;</span> <span class="js-cm">// Store the user's age</span></code></pre></div><p>Another example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span> <span class="js-id">total</span> <span class="js-op">=</span> <span class="js-id">price</span> <span class="js-op">*</span> <span class="js-id">quantity</span><span class="js-op">;</span> <span class="js-cm">// Calculate total cost</span></code></pre></div><p>This style can be useful for short explanations.</p><p>However, very long end-of-line comments can make code difficult to read.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Multiple Single-Line Comments</h2><p>You can use several <code dir="ltr">//</code> comments together:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Read the user's age.</span>
<span class="js-cm">// Validate the entered value.</span>
<span class="js-cm">// Display the result.</span>
<span class="js-id">int</span> <span class="js-id">age</span><span class="js-op">;</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cin</span> <span class="js-op">>></span> <span class="js-id">age</span><span class="js-op">;</span></code></pre></div><p>Each line begins with <code dir="ltr">//</code>.</p><p>This is still a collection of single-line comments rather than one multi-line comment.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">2. Multi-Line Comments in C++</h2><p>Multi-line comments begin with:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-op">/*</span></code></pre></div><p>and end with:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-op">*/</span></code></pre></div><p>Everything between these markers is treated as a comment.</p><p>Example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
This program calculates
the sum of two numbers.
*/</span>
#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span>
<span class="js-id">int</span> <span class="js-id">main</span><span class="js-op">()</span> <span class="js-op">{</span>
<span class="js-id">int</span> <span class="js-id">a</span> <span class="js-op">=</span> <span class="js-num">10</span><span class="js-op">;</span>
<span class="js-id">int</span> <span class="js-id">b</span> <span class="js-op">=</span> <span class="js-num">20</span><span class="js-op">;</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-id">a</span> <span class="js-op">+</span> <span class="js-id">b</span><span class="js-op">;</span>
<span class="js-kw">return</span> <span class="js-num">0</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>The entire section between <code dir="ltr">/*</code> and <code dir="ltr">*/</code> is ignored by the compiler.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">When Should You Use Multi-Line Comments?</h2><p>Multi-line comments are useful when you need to write a longer explanation.</p><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
The following calculation converts
a temperature from Celsius to Fahrenheit.
Formula:
F = (C × 9 / 5) + 32
*/</span>
<span class="js-id">double</span> <span class="js-id">fahrenheit</span> <span class="js-op">=</span> <span class="js-op">(</span><span class="js-id">celsius</span> <span class="js-op">*</span> <span class="js-num">9.0</span> <span class="js-op">/</span> <span class="js-num">5.0</span><span class="js-op">)</span> <span class="js-op">+</span> <span class="js-num">32.0</span><span class="js-op">;</span></code></pre></div><p>They can also be useful for describing a larger algorithm.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Single-Line vs Multi-Line Comments</h2><p>Here is the basic difference:</p><h3>Single-line</h3><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Calculate the total price</span>
<span class="js-id">double</span> <span class="js-id">total</span> <span class="js-op">=</span> <span class="js-id">price</span> <span class="js-op">*</span> <span class="js-id">quantity</span><span class="js-op">;</span></code></pre></div><h3>Multi-line</h3><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
Calculate the total price.
The result is based on:
price × quantity
*/</span>
<span class="js-id">double</span> <span class="js-id">total</span> <span class="js-op">=</span> <span class="js-id">price</span> <span class="js-op">*</span> <span class="js-id">quantity</span><span class="js-op">;</span></code></pre></div><p>Use the format that makes the explanation easiest to read.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments Do Not Affect Program Output</h2><p>Consider this program:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp">#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span>
<span class="js-id">int</span> <span class="js-id">main</span><span class="js-op">()</span> <span class="js-op">{</span>
<span class="js-cm">// This comment is ignored</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"Hello"</span><span class="js-op">;</span>
<span class="js-kw">return</span> <span class="js-num">0</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>The output is simply:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text"><span class="js-id">Hello</span></code></pre></div><p>The comment does not produce any output.</p><p>Similarly:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
This is a multi-line comment.
*/</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"Hello"</span><span class="js-op">;</span></code></pre></div><p>still produces:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text"><span class="js-id">Hello</span></code></pre></div><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments Can Be Used to Temporarily Disable Code</h2><p>Comments are sometimes useful when debugging.</p><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp">#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span>
<span class="js-id">int</span> <span class="js-id">main</span><span class="js-op">()</span> <span class="js-op">{</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"Start\n"</span><span class="js-op">;</span>
<span class="js-cm">// std::cout << "This line is temporarily disabled\n";</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"End\n"</span><span class="js-op">;</span>
<span class="js-kw">return</span> <span class="js-num">0</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>Output:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text"><span class="js-id">Start</span>
<span class="js-id">End</span></code></pre></div><p>The commented-out statement is not compiled as executable code.</p><p>You can also temporarily disable multiple lines:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
std::cout << "Line 1\n";
std::cout << "Line 2\n";
std::cout << "Line 3\n";
*/</span></code></pre></div><p>However, for long-term code maintenance, deleting obsolete code is usually better than keeping large blocks of commented-out code.</p><p>Version-control systems such as Git can preserve previous versions of the code.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments Inside C++ Code</h2><p>Comments can appear in different positions.</p><h3>Before code</h3><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Create a variable for the user's age.</span>
<span class="js-id">int</span> <span class="js-id">age</span> <span class="js-op">=</span> <span class="js-num">25</span><span class="js-op">;</span></code></pre></div><h3>After code</h3><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span> <span class="js-id">age</span> <span class="js-op">=</span> <span class="js-num">25</span><span class="js-op">;</span> <span class="js-cm">// User's age</span></code></pre></div><h3>Between statements</h3><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span> <span class="js-id">width</span> <span class="js-op">=</span> <span class="js-num">10</span><span class="js-op">;</span>
<span class="js-cm">// Calculate the area.</span>
<span class="js-id">int</span> <span class="js-id">area</span> <span class="js-op">=</span> <span class="js-id">width</span> <span class="js-op">*</span> <span class="js-id">width</span><span class="js-op">;</span></code></pre></div><h3>Multi-line</h3><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
Calculate the area
of a square.
*/</span>
<span class="js-id">int</span> <span class="js-id">area</span> <span class="js-op">=</span> <span class="js-id">width</span> <span class="js-op">*</span> <span class="js-id">width</span><span class="js-op">;</span></code></pre></div><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments and Whitespace</h2><p>C++ ignores comments and generally treats them as whitespace during preprocessing.</p><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span><span class="js-cm">/*comment*/</span><span class="js-id">main</span><span class="js-op">()</span></code></pre></div><p>is syntactically possible in contexts where the resulting tokens remain valid, although writing code this way is strongly discouraged because it hurts readability.</p><p>Prefer:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span> <span class="js-id">main</span><span class="js-op">()</span></code></pre></div><p>Comments should make source code easier to understand, not harder.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Documentation Comments in C++</h2><p>Many C++ projects use special comments to generate documentation.</p><p>One of the most popular tools is <strong>Doxygen</strong>.</p><p>Doxygen can process specially formatted comments and generate documentation for:</p><ul data-spread="false"><li><p>Classes</p></li><li><p>Functions</p></li><li><p>Variables</p></li><li><p>Namespaces</p></li><li><p>Files</p></li><li><p>Parameters</p></li><li><p>Return values</p></li></ul><p>A common Doxygen-style comment is:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Adds two integers.
*
* @param a First integer.
* @param b Second integer.
* @return The sum of a and b.
*/</span>
<span class="js-id">int</span> <span class="js-id">add</span><span class="js-op">(</span><span class="js-id">int</span> <span class="js-id">a</span><span class="js-op">,</span> <span class="js-id">int</span> <span class="js-id">b</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-id">a</span> <span class="js-op">+</span> <span class="js-id">b</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>The comment is still a C++ comment, but its structured format provides information that documentation tools can understand.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3"><code dir="ltr">///</code> Documentation Comments</h2><p>Another common documentation style uses three slashes:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/// Calculates the area of a circle.</span>
<span class="js-id">double</span> <span class="js-id">area</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">radius</span><span class="js-op">);</span></code></pre></div><p>A longer example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/// Calculates the area of a circle.</span>
<span class="js-cm">///</span>
<span class="js-cm">/// @param radius Circle radius.</span>
<span class="js-cm">/// @return Area of the circle.</span>
<span class="js-id">double</span> <span class="js-id">area</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">radius</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-num">3.14159</span> <span class="js-op">*</span> <span class="js-id">radius</span> <span class="js-op">*</span> <span class="js-id">radius</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>The exact documentation syntax supported depends on the documentation tool and project configuration.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3"><code dir="ltr">/** ... */</code> Documentation Style</h2><p>Doxygen commonly uses:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Calculates the area of a circle.
*
* @param radius Circle radius.
* @return Circle area.
*/</span>
<span class="js-id">double</span> <span class="js-id">area</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">radius</span><span class="js-op">);</span></code></pre></div><p>This style is particularly useful for public APIs.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Common Doxygen Tags</h2><p>Some frequently used Doxygen tags include:</p><table><tbody><tr><th>Tag</th><th>Purpose</th></tr><tr><td><code dir="ltr">@param</code></td><td>Describes a function parameter</td></tr><tr><td><code dir="ltr">@return</code></td><td>Describes the return value</td></tr><tr><td><code dir="ltr">@brief</code></td><td>Provides a short description</td></tr><tr><td><code dir="ltr">@note</code></td><td>Adds an important note</td></tr><tr><td><code dir="ltr">@warning</code></td><td>Adds a warning</td></tr><tr><td><code dir="ltr">@see</code></td><td>References related documentation</td></tr><tr><td><code dir="ltr">@deprecated</code></td><td>Marks an API as deprecated</td></tr></tbody></table><p>Example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* @brief Calculates the total price.
*
* @param price Price of one item.
* @param quantity Number of items.
* @return Total price.
*/</span>
<span class="js-id">double</span> <span class="js-id">calculateTotal</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">price</span><span class="js-op">,</span> <span class="js-id">int</span> <span class="js-id">quantity</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-id">price</span> <span class="js-op">*</span> <span class="js-id">quantity</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>This makes the function's purpose and interface easier to understand.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Commenting Functions</h2><p>A function should sometimes have a comment explaining its purpose.</p><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Calculates the average of two numbers.</span>
<span class="js-id">double</span> <span class="js-id">average</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">a</span><span class="js-op">,</span> <span class="js-id">double</span> <span class="js-id">b</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-op">(</span><span class="js-id">a</span> <span class="js-op">+</span> <span class="js-id">b</span><span class="js-op">)</span> <span class="js-op">/</span> <span class="js-num">2</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>For a public library API, structured documentation may be more useful:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Calculates the average of two numbers.
*
* @param a First number.
* @param b Second number.
* @return Average of the two numbers.
*/</span>
<span class="js-id">double</span> <span class="js-id">average</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">a</span><span class="js-op">,</span> <span class="js-id">double</span> <span class="js-id">b</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-op">(</span><span class="js-id">a</span> <span class="js-op">+</span> <span class="js-id">b</span><span class="js-op">)</span> <span class="js-op">/</span> <span class="js-num">2</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Commenting Classes</h2><p>Comments can explain the purpose of a class.</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Represents a simple bank account.
*/</span>
<span class="js-kw">class</span> <span class="js-id">BankAccount</span> <span class="js-op">{</span>
<span class="js-id">public</span><span class="js-op">:</span>
<span class="js-kw">void</span> <span class="js-id">deposit</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">amount</span><span class="js-op">);</span>
<span class="js-kw">void</span> <span class="js-id">withdraw</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">amount</span><span class="js-op">);</span>
<span class="js-op">};</span></code></pre></div><p>For larger projects, documenting public classes and their important methods can significantly improve maintainability.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Good Comments Explain Why</h2><p>One of the most important commenting principles is:</p><blockquote><p>Prefer comments that explain <strong>why</strong> something is done rather than comments that simply repeat <strong>what</strong> the code already says.</p></blockquote><p>Consider:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Increment i by</span>
<span class="js-num">1</span><span class="js-op">.</span>
<span class="js-id">i</span><span class="js-op">++;</span></code></pre></div><p>This comment provides almost no useful information because the code is already obvious.</p><p>A better comment might explain an unusual decision:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Start at index 1 because index 0 contains the header row.</span>
<span class="js-kw">for</span> <span class="js-op">(</span><span class="js-id">int</span> <span class="js-id">i</span> <span class="js-op">=</span> <span class="js-num">1</span><span class="js-op">;</span> <span class="js-id">i</span> <span class="js-op"><</span> <span class="js-id">rows</span><span class="js-op">.</span><span class="js-id">size</span><span class="js-op">();</span> <span class="js-op">++</span><span class="js-id">i</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-cm">// Process row</span>
<span class="js-op">}</span></code></pre></div><p>The comment provides information that cannot immediately be understood from the syntax alone.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Bad Comments vs Good Comments</h2><h2>Bad Comment</h2><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Add 1 to count.</span>
<span class="js-id">count</span><span class="js-op">++;</span></code></pre></div><p>The code already explains what happens.</p><h2>Better Comment</h2><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Skip the header row when counting data records.</span>
<span class="js-id">count</span><span class="js-op">++;</span></code></pre></div><p>The second comment provides context.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Avoid Obvious Comments</h2><p>Avoid writing comments like:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span> <span class="js-id">age</span> <span class="js-op">=</span> <span class="js-num">30</span><span class="js-op">;</span> <span class="js-cm">// Set age to 30</span></code></pre></div><p>This does not provide meaningful information.</p><p>Instead, if the value has a specific reason:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">int</span> <span class="js-id">minimumAge</span> <span class="js-op">=</span> <span class="js-num">18</span><span class="js-op">;</span> <span class="js-cm">// Minimum age required for account registration.</span></code></pre></div><p>The comment adds useful context.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments Should Stay Accurate</h2><p>An incorrect comment can be worse than no comment.</p><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Calculate the square.</span>
<span class="js-id">int</span> <span class="js-id">result</span> <span class="js-op">=</span> <span class="js-id">width</span> <span class="js-op">*</span> <span class="js-id">height</span><span class="js-op">;</span></code></pre></div><p>If the code calculates the area of a rectangle, the comment is misleading.</p><p>Keep comments synchronized with the code.</p><p>When changing code, review related comments as well.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Avoid Huge Comment Blocks</h2><p>Large comment blocks can make source code difficult to navigate.</p><p>Instead of:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
This function receives the user's age.
It checks whether the age is greater than or
equal to
18. If it is, the function returns
true. Otherwise, it returns false. The function
is used to determine whether the user can
register for the service.
*/</span>
<span class="js-id">bool</span> <span class="js-id">isAdult</span><span class="js-op">(</span><span class="js-id">int</span> <span class="js-id">age</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-id">age</span> <span class="js-op">>=</span> <span class="js-num">18</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>A concise explanation may be enough:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Returns true when the user meets the minimum age requirement.</span>
<span class="js-id">bool</span> <span class="js-id">isAdult</span><span class="js-op">(</span><span class="js-id">int</span> <span class="js-id">age</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-id">age</span> <span class="js-op">>=</span> <span class="js-num">18</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>For a public API, structured documentation can be appropriate:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Checks whether a user meets the minimum age requirement.
*
* @param age User's age.
* @return true if the user is at least 18; otherwise false.
*/</span>
<span class="js-id">bool</span> <span class="js-id">isAdult</span><span class="js-op">(</span><span class="js-id">int</span> <span class="js-id">age</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-id">age</span> <span class="js-op">>=</span> <span class="js-num">18</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">TODO Comments</h2><p>Developers sometimes use comments to mark unfinished work.</p><p>Example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// TODO: Add input validation.</span></code></pre></div><p>Another example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// TODO: Replace this temporary implementation.</span></code></pre></div><p>TODO comments can be useful during development, especially when an IDE or code-review system can track them.</p><p>However, unfinished TODOs should be reviewed regularly.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">FIXME Comments</h2><p><code dir="ltr">FIXME</code> is another commonly used convention.</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// FIXME: Handle invalid input correctly.</span></code></pre></div><p>It signals that something needs correction.</p><p>Other project-specific markers may include:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// NOTE: This function is intentionally synchronous.</span>
<span class="js-cm">// HACK: Required for compatibility with the legacy API.</span>
<span class="js-cm">// WARNING: Changing this value affects existing users.</span></code></pre></div><p>These are conventions rather than special C++ language features.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments and Preprocessor Directives</h2><p>C++ source code often contains preprocessor directives such as:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp">#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span></code></pre></div><p>Comments can be placed around them:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Standard input/output functionality</span>
#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span></code></pre></div><p>You can also comment out a preprocessor directive:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// #include <some-library.h></span></code></pre></div><p>The compiler will no longer process that line as an active directive.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Nested Multi-Line Comments</h2><p>A common beginner mistake is trying to nest block comments.</p><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
Outer comment
/*
Inner comment
*/</span>
<span class="js-id">More</span> <span class="js-id">text</span>
<span class="js-op">*/</span></code></pre></div><p>C++ block comments do <strong>not</strong> nest in the way beginners often expect.</p><p>This can cause confusing compilation errors because the first <code dir="ltr">*/</code> ends the comment.</p><p>If you need to temporarily disable a section that already contains block comments, using <code dir="ltr">//</code> on each line or an editor's comment toggle is often safer.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments Inside Strings Are Not Comments</h2><p>Consider:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"// This is not a comment"</span><span class="js-op">;</span></code></pre></div><p>The text:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text"><span class="js-cm">// This is not a comment</span></code></pre></div><p>is inside a string literal.</p><p>It is printed as normal text.</p><p>Similarly:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"/* Not a comment */"</span><span class="js-op">;</span></code></pre></div><p>prints:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text"><span class="js-cm">/* Not a comment */</span></code></pre></div><p>The compiler recognizes the comment markers as ordinary characters because they are inside the string.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comment Examples</h2><h2>Single-Line</h2><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Calculate the total.</span>
<span class="js-id">double</span> <span class="js-id">total</span> <span class="js-op">=</span> <span class="js-id">price</span> <span class="js-op">*</span> <span class="js-id">quantity</span><span class="js-op">;</span></code></pre></div><h2>Multi-Line</h2><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
Calculate the total price
using price and quantity.
*/</span>
<span class="js-id">double</span> <span class="js-id">total</span> <span class="js-op">=</span> <span class="js-id">price</span> <span class="js-op">*</span> <span class="js-id">quantity</span><span class="js-op">;</span></code></pre></div><h2>Documentation</h2><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Calculates the total price.
*
* @param price Price per item.
* @param quantity Number of items.
* @return Total price.
*/</span>
<span class="js-id">double</span> <span class="js-id">calculateTotal</span><span class="js-op">(</span><span class="js-id">double</span> <span class="js-id">price</span><span class="js-op">,</span> <span class="js-id">int</span> <span class="js-id">quantity</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-id">price</span> <span class="js-op">*</span> <span class="js-id">quantity</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><h2>TODO</h2><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// TODO: Add error handling.</span></code></pre></div><h2>FIXME</h2><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// FIXME: Validate negative values.</span></code></pre></div><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">C++ Comment Best Practices</h2><p>Follow these practices when writing comments.</p><h3>1. Explain intent</h3><p>Tell readers why a non-obvious decision was made.</p><h3>2. Keep comments concise</h3><p>Use the smallest explanation that provides useful information.</p><h3>3. Keep comments accurate</h3><p>Update comments when the code changes.</p><h3>4. Avoid repeating obvious code</h3><p>Do not describe every simple statement.</p><h3>5. Document public APIs</h3><p>Functions, classes, and interfaces used by other developers often benefit from structured documentation.</p><h3>6. Prefer clear code</h3><p>Good naming and simple structure can reduce the need for comments.</p><h3>7. Remove obsolete comments</h3><p>Old comments can confuse future developers.</p><h3>8. Use a consistent documentation style</h3><p>If a project uses Doxygen, follow its established format.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Comments vs Documentation</h2><p>Comments and documentation are related but are not exactly the same.</p><h3>Comments</h3><p>Usually help developers understand implementation details.</p><p>Example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Ignore the first row because it contains column names.</span></code></pre></div><h3>Documentation</h3><p>Usually describes how an API, class, function, or library should be used.</p><p>Example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Calculates the total price.
*
* @param price Price of one item.
* @param quantity Number of items.
* @return Total price.
*/</span></code></pre></div><p>Documentation is especially important for libraries and large applications.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Do Comments Increase Program Size?</h2><p>In a normal compiled C++ application, comments are not executable instructions.</p><p>The compiler processes source code and the resulting executable does not normally contain ordinary source comments as executable code.</p><p>Therefore, adding a normal comment such as:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// Calculate the total.</span></code></pre></div><p>does not make the program perform an additional operation at runtime.</p><p>Comments primarily exist to improve the source code for humans and documentation tools.</p><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">A Practical C++ Example</h2><p>Here is a small program using several useful commenting styles:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp">#<span class="js-id">include</span> <span class="js-op"><</span><span class="js-id">iostream</span><span class="js-op">></span>
<span class="js-cm">// Calculate the sum of two integers.</span>
<span class="js-id">int</span> <span class="js-id">add</span><span class="js-op">(</span><span class="js-id">int</span> <span class="js-id">a</span><span class="js-op">,</span> <span class="js-id">int</span> <span class="js-id">b</span><span class="js-op">)</span> <span class="js-op">{</span>
<span class="js-kw">return</span> <span class="js-id">a</span> <span class="js-op">+</span> <span class="js-id">b</span><span class="js-op">;</span>
<span class="js-op">}</span>
<span class="js-cm">/**
* Program entry point.
*
* Demonstrates a simple function and output.
*/</span>
<span class="js-id">int</span> <span class="js-id">main</span><span class="js-op">()</span> <span class="js-op">{</span>
<span class="js-id">int</span> <span class="js-id">first</span> <span class="js-op">=</span> <span class="js-num">10</span><span class="js-op">;</span>
<span class="js-id">int</span> <span class="js-id">second</span> <span class="js-op">=</span> <span class="js-num">20</span><span class="js-op">;</span>
<span class="js-cm">// Calculate the result.</span>
<span class="js-id">int</span> <span class="js-id">result</span> <span class="js-op">=</span> <span class="js-id">add</span><span class="js-op">(</span><span class="js-id">first</span><span class="js-op">,</span> <span class="js-id">second</span><span class="js-op">);</span>
<span class="js-id">std</span><span class="js-op">::</span><span class="js-id">cout</span> <span class="js-op"><<</span> <span class="js-str">"Sum = "</span> <span class="js-op"><<</span> <span class="js-id">result</span> <span class="js-op"><<</span> <span class="js-str">"\n"</span><span class="js-op">;</span>
<span class="js-kw">return</span> <span class="js-num">0</span><span class="js-op">;</span>
<span class="js-op">}</span></code></pre></div><p>Output:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text"><span class="js-id">Sum</span> <span class="js-op">=</span> <span class="js-num">30</span></code></pre></div><p>This example demonstrates:</p><ul data-spread="false"><li><p>Single-line comments</p></li><li><p>Documentation-style comments</p></li><li><p>Functions</p></li><li><p>Variables</p></li><li><p>Function calls</p></li><li><p>Output</p></li></ul><div><hr></div><h2 class="h4 fw-bold text-dark mb-3">Frequently Asked Questions</h2><h2>What are comments in C++?</h2><p>Comments are explanatory text in C++ source code that is ignored as executable code by the compiler. They are used to explain code and document programs.</p><h2>How do you write a single-line comment in C++?</h2><p>Use two forward slashes:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">// This is a C++ comment.</span></code></pre></div><p>Everything after <code dir="ltr">//</code> on that line is treated as a comment.</p><h2>How do you write a multi-line comment in C++?</h2><p>Use <code dir="ltr">/*</code> to start the comment and <code dir="ltr">*/</code> to end it:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/*
This is a
multi-line comment.
*/</span></code></pre></div><h2>What is the difference between <code dir="ltr">//</code> and <code dir="ltr">/* */</code>?</h2><p><code dir="ltr">//</code> creates a single-line comment, while <code dir="ltr">/* ... */</code> can span multiple lines.</p><h2>What are documentation comments in C++?</h2><p>Documentation comments are specially formatted comments that documentation tools can process. Doxygen is a popular example.</p><p>For example:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-cpp"><span class="js-cm">/**
* Adds two numbers.
*
* @param a First number.
* @param b Second number.
* @return Sum of the numbers.
*/</span></code></pre></div><h2>Does C++ execute comments?</h2><p>No. Comments are not executed as program instructions.</p><h2>Can comments be used to disable C++ code?</h2><p>Yes. Code can temporarily be placed inside comments, although long-term obsolete code is generally better removed and recovered through version control when needed.</p><h2>Can C++ comments be nested?</h2><p>Block comments using <code dir="ltr">/* ... */</code> should not be treated as nestable comments. Nested block-comment syntax can cause unexpected results.</p><h2>Should every line of C++ code have a comment?</h2><p>No. Over-commenting can make code harder to read. Good code should be understandable through clear naming and structure, with comments added where they provide useful context.</p><h2>Which comments should I use in C++?</h2><p>Use <code dir="ltr">//</code> for short explanations and <code dir="ltr">/* ... */</code> when a block comment is more appropriate. For public APIs, consider a consistent documentation style such as Doxygen.</p><h2 data-pm-slice="1 1 []">Suggested Graphic Design</h2><p>Create a clean programming infographic titled:</p><p><strong>“C++ Comments: 3 Common Styles”</strong></p><p>Show three side-by-side sections:</p><div class="code-card position-relative my-2">
<div class="code-card-actions">
<button type="button" class="btn-code-action copy-code-btn" onclick="copyCode(this)" title="Copy Code">
<i class="far fa-copy"></i>
</button>
<a href="/tools/cpp-compiler" target="_blank" class="btn-code-action run-code-btn" title="Run Online">
<i class="fas fa-play"></i>
</a>
</div>
<pre class="code-box"><code class="language-text">┌─────────────────────┐
│ <span class="js-id">SINGLE</span><span class="js-op">-</span><span class="js-id">LINE</span> │
│ │
│ <span class="js-cm">// Explain code │</span>
│ <span class="js-id">int</span> <span class="js-id">age</span> <span class="js-op">=</span> <span class="js-num">25</span><span class="js-op">;</span> │
└─────────────────────┘
┌─────────────────────┐
│ <span class="js-id">MULTI</span><span class="js-op">-</span><span class="js-id">LINE</span> │
│ │
│ <span class="js-cm">/* │
│ Explain code │
│ over lines │
│ */</span> │
└─────────────────────┘
┌─────────────────────┐
│ <span class="js-id">DOCUMENTATION</span> │
│ │
│ <span class="js-cm">/** │
│ * @param value │
│ * @return result │
│ */</span> │
└─────────────────────┘</code></pre></div><p>Add a small footer:</p><p><strong>“Comments help people understand code — the compiler ignores ordinary comments.”</strong></p><p><strong>Suggested image alt text:</strong><br><code dir="ltr">C++ comments guide showing single-line, multi-line, and documentation comment syntax with examples</code></p>
Code Example
#include <iostream>
/**
* @brief Calculates the total price including tax.
* @param netPrice The base price of the item before tax.
* @param taxRate The percentage tax rate (e.g., 0.18 for 18%).
* @return double The gross calculated price.
*/
double calculateGrossPrice(double netPrice, double taxRate) {
// Validate inputs are non-negative
if (netPrice < 0.0 || taxRate < 0.0) {
return 0.0;
}
/*
* Computation formula:
* gross = netPrice * (1.0 + taxRate)
*/
double gross = netPrice * (1.0 + taxRate);
return gross;
}
int main() {
double total = calculateGrossPrice(100.0, 0.18);
std::cout << "Calculated Gross Price: $" << total << "
";
return 0;
}Interview Question & Tips
A: No. The first `*/` encountered will close the entire block. To comment out code blocks containing existing comments, use `#if 0 ... #endif`.
Q: What tool is used to parse C++ documentation comments into HTML?
A: Doxygen is the industry-standard documentation generator for C++ codebases.
Best Practices
2. Document public API headers thoroughly with Doxygen tags.
3. Write comments that explain the architectural intent and edge cases rather than repeating the syntax.
This study reference for C++ Comments Guide: Single-Line, Multi-Line, and Documentation Styles is curated and verified against recognized curriculum benchmarks, peer-reviewed textbooks, and official technical documentation: