Minimize the Need to Align Comment Boilerplate Markers [DM3]

Tip DM3

It can be very tempting to try aligning comment content to make it look “nice-and-pretty” in the code. However, keeping such content aligned can take extra time, discouraging people from keeping the comments up-to-date. Prefer styles that don’t require much alignment effort.

For example, the following style aims to align certain parts of the comments, notably the ending */ comment markers:

struct Color
{
    /**     The red channel of the color,   between [0,1].    */
    float Red = 0.0f;
    /**     The green channel of the color, between [0,1].    */
    float Green = 0.0f;
    /**     The blue channel of the color,  between [0,1].    */
    float Blue = 0.0f;
    /**     The alpha channel of the color, between [0,1].    */
    float Alpha = 1.0f;
};

Removing the need to keep such alignment shouldn’t drastically hurt readability and should be easier to maintain should comments need to change (though see the tip below on handling multiline comment markers):

struct Color
{
    /** The red channel of the color, between [0,1]. */
    float Red = 0.0f;
    /** The green channel of the color, between [0,1]. */
    float Green = 0.0f;
    /** The blue channel of the color, between [0,1]. */
    float Blue = 0.0f;
    /** The alpha channel of the color, between [0,1]. */
    float Alpha = 1.0f;
};

Comment marker alignment can also be particularly tempting when providing function header documentation in various documentation generator styles:

/***********************************************************************************
 * Sends the provided emails.                                                      *
 * @param   emails          - The emails to send.                                  *
 * @param   emailAddress    - The address to send the emails to.                   *
 * @return  True if emails were sent successfully;                                 *
 *          false if all emails failed to be sent.                                 *
 ***********************************************************************************/

Such a box might book nice in the code. However, not only is such a style hard-to-maintain (likely to result in a lot of fussing with the asterisks at the end of each line), but most modern documentation generators will render ending comment markers for the * as actual text in the generated HTML documentation, resulting in less-readable documentation.

The following style is much more streamlined:

/**
 * Sends the provided emails.
 * @param emails The emails to send.
 * @param emailAddress The address to send the emails to.
 * @return  True if emails were sent successfully;
 *    false if all emails failed to be sent.
 */

Some alignment is nice, but most programmers will typically tap-out at one or two presses of the “tab” key. Anything more than that can become too cumbersome to maintain.