Leverage Blank Lines to Separate “Paragraphs” of Documentation [DS26]
Tip DS26
When dealing with comments, use blank lines to separate “paragraphs” covering different topics. In other written communication, we use indentation or blank lines to separate paragraphs or groups of sentences that cover different thoughts. The same kind of practice is effective in comments.
Don’t give readers a “huge wall of text” to sift through to try and find what they’re looking for. Divide longer comments into chunks, each with a cohesive focus, so that readers can more easily find and grasp what you’re writing about.
In most cases, a single blank line of space is sufficient visual separation - using more than one blank line is usually not worth the cost of the extra separation due to reducing what can be displayed on-screen at once.
The following example separates the most high-level overview for a class from finer-grained details:
/// A random number generator. This class serves to provide a more
/// convenient interface (compared to the built-in C++ libraries)
/// for certain situations of generating random numbers.
///
/// Many methods are templated to let them adapt to different data types,
/// but no special logic exists for these types (they're basically just
/// casted directly to from unsigned integers).