C++ Comments

Comments are non-executable annotations that help humans understand code. The compiler discards them during compilation, so they do not affect program behavior or runtime performance. C++ supports two primary styles - single-line and multi-line - for different documentation needs.

Use comments to clarify intent and design decisions; avoid storing sensitive information in comments since they are not a security mechanism.

Comment markers inside string or character literals are not comments (e.g., "//" inside a string stays part of the string).

Single-line comments begin with two forward slashes (//) and extend to the end of the line. They are useful for short notes or inline explanations.

For longer notes or temporarily disabling a small block of code, use /* ... */ to create a multi-line comment.

For larger sections, prefer conditional compilation so you don't run into nested block-comment issues.

Effective commenting follows these guidelines:

Strive for readable code first; use comments to explain intent, assumptions, edge cases, and trade-offs.

During debugging, comments can temporarily disable code paths or mark sections for review.

Structured comments can be processed by tools (e.g., Doxygen) to generate API documentation.

These documentation styles are conventions used by tools, not special syntax in the C++ language standard. Use a consistent documentation style across the codebase so generated references remain clear and useful.

In production code, comments document configuration, intent, and non-obvious behaviors.