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.