Comments

3 min read C / C++

The Purpose of Comments

Comments explain the why of code, not the what. Well-written code is largely self-documenting through meaningful names and clear structure. Comments fill the gaps: they explain design decisions, warn about non-obvious behavior, and describe the intent behind algorithms.

A comment that just restates the code adds no value:

/* Increment i by 1 */
i++;

A comment that explains intent does:

/* Retry count starts at 1 because the first attempt is not considered a retry */
int retryCount = 1;

Documentation Comments and Tools

Documentation tools can extract structured comments from source code and generate API reference documentation automatically.

Doxygen (C / C++)

Doxygen is the standard documentation tool for C and C++. Special comment blocks beginning with /** or /*! are parsed by Doxygen to produce HTML, PDF, and other formats.

/**
 * @brief  Calculate the area of a circle.
 * @param  radius  The radius of the circle (must be positive).
 * @return The area in square units.
 */
double circleArea(double radius) {
    return 3.14159265 * radius * radius;
}

Common Doxygen tags:

@brief — Short description
@param — Documents a parameter
@return — Documents the return value
@note — Adds a note
@warning — Highlights a warning
@see — Cross-reference to related items
@todo — Marks a to-do item

JavaDoc (Java)

JavaDoc uses /** ... */ comment blocks with @tag annotations, and is built into the Java Development Kit.

/**
 * Returns the absolute value of an integer.
 *
 * @param  value  the input integer
 * @return        the absolute value of {@code value}
 */
public int abs(int value) {
    return value < 0 ? -value : value;
}

XML Documentation Comments (C#)

C# supports XML-based documentation comments that are processed by tools like Sandcastle or DocFX:

/// <summary>
/// Calculates the area of a rectangle.
/// </summary>
/// <param name="width">The width of the rectangle.</param>
/// <param name="height">The height of the rectangle.</param>
/// <returns>The area of the rectangle.</returns>
public int RectangleArea(int width, int height) {
    return width * height;
}

CVS and Comment Conventions

In CVS (Concurrent Versions System, one of the early version control systems), check-in comments document why a change was made. These log messages become the project's change history. Good CVS commit messages follow the same principle as good code comments: explain the reason for the change, not the mechanical description of what lines changed.

The conventions established in the CVS era — writing commit messages that explain intent and reference issue numbers — carry directly forward to modern Git workflows.

Comment Best Practices

Write comments before you write the code — Describing what a function should do before implementing it often reveals design problems early.
Keep comments current — An outdated comment is worse than no comment; it actively misleads.
Comment complex algorithms — If you implement a non-obvious algorithm, cite the source (paper, book, or URL) and explain the key idea.
Use TODO and FIXME markers — Most editors and IDEs highlight these, making them easy to find.
Don't comment out dead code — Delete it; version control will preserve the history if you ever need it back.
Comment public APIs thoroughly — Internal implementation can sometimes speak for itself, but public interfaces should always be documented.