Consistent and comprehensive in-code commenting is crucial for maintaining the readability, understanding, and long-term viability of the C++ codebase. This document outlines the guidelines for C++ comments, emphasizing Doxygen-style comments for public interfaces and complex logic.
- Focus on Why, not What: Comments should explain the reasoning behind a piece of code, its purpose, its design choices, and its interaction with other components. Avoid simply re-stating what the code visibly does.
- Keep it Concise and Clear: Comments should be easy to understand and avoid unnecessary jargon or excessive length.
- Maintain with Code: Outdated comments are worse than no comments. Always update comments when the corresponding code changes.
- Avoid Redundancy: Do not comment on obvious code.
- English Language: All comments must be written in English.
All public classes, structs, enums, functions, and significant members that form part of the API or are intended for broader use within the project must be documented using Doxygen-style comments. This allows for automated documentation generation and provides a structured way to convey essential information.
Each .h and .cpp file should start with a Doxygen-style file header:
/**
* @file MyModule.h
* @brief Brief description of the file's purpose.
*
* Detailed explanation of what this file contains, its responsibilities,
* and any important design considerations or dependencies.
*/
#pragma once // Or traditional include guards
// ... rest of the filePublic classes and structs should have a Doxygen comment immediately preceding their definition.
/**
* @class MyClass
* @brief Brief description of MyClass's purpose.
*
* Detailed explanation of the class's responsibilities, its role in the system,
* and any significant design patterns or invariants.
*/
class MyClass
{
public:
// ... members
};Public enums should be documented, along with individual enumerators if their meaning is not self-evident.
/**
* @enum MyEnum
* @brief Brief description of MyEnum's purpose.
*
* Detailed explanation of when and why this enum is used.
*/
enum class MyEnum {
/** @brief Represents the first state. */
STATE_ONE,
/** @brief Represents the second state. */
STATE_TWO,
STATE_THREE /**< Represents the third state (alternative style). */
};All public (and protected/private if complex or critical) functions/methods should be documented with their purpose, parameters, and return values.
/**
* @brief Calculates the sum of two integers.
*
* This function takes two integer inputs and returns their sum.
* It handles potential overflow by clamping the result to INT_MAX/INT_MIN,
* although not explicitly shown here.
*
* @param a The first integer operand.
* @param b The second integer operand.
* @return The sum of 'a' and 'b'.
* @exception std::overflow_error If the sum exceeds the integer limits. (Example)
* @note This function is thread-safe. (Example)
*/
int calculateSum(int a, int b);
/**
* @brief Processes a list of items and performs a specific action.
*
* @param items A reference to the vector of items to process. Modified in-place.
* @param action The specific action to perform on each item.
* @return True if all items were processed successfully, false otherwise.
*/
bool processItems(std::vector<Item>& items, ActionType action);Common Doxygen Tags:
@brief: A concise, one-line summary of the entity's purpose.@param <name>: Description of a function parameter.@return: Description of the function's return value.@see: Reference to related documentation or code.@note: Important notes or considerations.@warning: Warnings about potential pitfalls or usage restrictions.@todo: A pending task or improvement.@exception: Describes exceptions that might be thrown.
For internal logic, algorithms, or non-public members, use standard C++ line (//) or block (/* ... */) comments. These comments do not need to follow Doxygen's strict format but should adhere to the general principles:
// This local variable stores the intermediate result of the complex calculation.
int intermediateResult = computeComplexValue(input);
/*
* The following block performs an optimization based on the XYZ algorithm.
* It's critical for performance in large datasets, avoiding N^2 complexity.
*/
if (shouldOptimize) {
// ... optimized logic ...
} else {
// ... fallback logic ...
}- Doxygen: Use the Doxygen tool to generate API documentation from these comments. Ensure your Doxygen configuration is set up to parse the codebase and generate the desired output formats (e.g., HTML, Markdown).
- Static Analyzers: Consider integrating static analysis tools that can check for missing comments on public APIs (e.g., some linters might have checks for missing Doxygen blocks).
By consistently applying these guidelines, the C++ codebase for AgentSimMiddleware will be more maintainable, understandable, and accessible to current and future developers.