Add explanatory comments for any code element that is not self-explanatory, including complex return types, method parameters, classes, and technical concepts that may not be familiar to all developers.
Key areas requiring documentation:
std::pair or other composite types should explain what each element representsExamples:
// Bad - no explanation of return values
std::pair<NamesAndTypesList, NamesAndTypesList> setupHivePartitioning(...);
// Good - clear explanation
/// Returns a pair of (partition_columns, regular_columns) extracted from the path
std::pair<NamesAndTypesList, NamesAndTypesList> setupHivePartitioning(...);
// Bad - no explanation of parameter
void prepareProcessedRequests(Coordination::Requests & requests,
LastProcessedFileInfoMapPtr created_nodes = nullptr);
// Good - parameter purpose explained
/// Prepare keeper requests, required to set file as Processed.
/// @param created_nodes - map of newly created nodes for tracking, passed when...
void prepareProcessedRequests(Coordination::Requests & requests,
LastProcessedFileInfoMapPtr created_nodes = nullptr);
// Bad - no class documentation
struct HiveStylePartitionStrategy : PartitionStrategy
// Good - explains the concept
/// Implements Hive-style partitioning where data is organized into directories
/// based on partition key values (e.g., year=2023/month=01/data.parquet)
struct HiveStylePartitionStrategy : PartitionStrategy
The goal is to make code self-documenting and reduce the cognitive load for future maintainers who may not be familiar with the specific domain or implementation details.
Enter the URL of a public GitHub repository