Comment All The Things!

Comments are good. At least that’s my default disposition. Although they don’t take the place of proper end-user documentation, or architecture documentation, they serve as a helpful guide to future code spelunkers.

In the past, I’ve always used a 3rd party plugin or tool (something like Visual Assist) for quick and easy function header comment templates. With the latest version of Visual Studio 2019, those days are gone.

Default Comment Blocks

By default, if you type three forward slashes (///), an XML Doc comment will be spawned:

Example:

/// <summary>
/// 
/// </summary>
/// <param name="pJob"></param>
/// <param name="pParent"></param>
void Fiber::Activate(Job* pJob, Fiber* pParent) {

    // The thread that we'll switch back to when the job is complete

Here’s an example of that key combination in action:

That’s fine and all, but I’m more of a Doxygen kind of guy. Thankfully, there’s an option for that now!

Enabling Doxygen

Navigate to Tools -> Options -> Text Edtitor -> C/C++ -> Code Style -> General.

NOTE: If Code Style isn’t available in the C/C++ section, you need to upgrade your version of Visual Studio.

From there’ you’ll be provided with a drop down showing the following options

Each Doxygen option will allow you to use a different key sequence to start a header. In turn, each different key sequence will also generate a slightly different format of the header.

`///`

Replaces the standard XML Doc key sequence with a simple single line comment version of the function docstring.

/// @brief 
/// @param pJob 
/// @param pParent 
void Fiber::Activate(Job* pJob, Fiber* pParent) {

    // The thread that we'll switch back to when the job is complete
    m_pParent = pParent;

`/**`

Multi-line version of the Doxygen function header docstring.

/**
 * @brief 
 * @param pJob 
 * @param pParent 
*/
void Fiber::Activate(Job* pJob, Fiber* pParent) {

    // The thread that we'll switch back to when the job is complete
    m_pParent = pParent;

`/*!`

Slight variation on the multiline comment docstring.

/*!
 * @brief 
 * @param pJob 
 * @param pParent 
*/
void Fiber::Activate(Job* pJob, Fiber* pParent) {

    // The thread that we'll switch back to when the job is complete
    m_pParent = pParent;

`//!`

Another version of the single line docstring template.

//! @brief 
//! @param pJob 
//! @param pParent 
void Fiber::Activate(Job* pJob, Fiber* pParent) {

    // The thread that we'll switch back to when the job is complete
    m_pParent = pParent;

And that’s it! Go forth…and sprinkle well commented function and method headers throughout your codebase!

~Zim