Best practice for C++ function commenting [closed]

Question

There only general thing most people will agree with is that comments should say "why", not "what". Other than that, guidelines depend on the coding standards at your place of work.

Personally, I hate doxygen and the like, because it contradicts the first thing I said. The "documentation", if it can be called that, is just a prettified header file. And the cost? Nearly duplicated code, obtrusive comments (seriously, it doubles the height of everything), and just a pain.

Your code should be self-documenting: use descriptive names, factor everything into well-defined tasks, etc. The only comments should be things that may need clarification.

For example, an excerpt from a network socket class I wrote:

const bool socket_connected(void) const;

You already know what this function does; I don't need to explain it. Do I really need to add a big chunk of comment explaining that it returns a boolean (duh) that will indicate of the socket is connected (duh)? No. doxygen is just going to take my header and add some fancy style-sheet to it.

Here's an example where a quick note may be useful (making this class up):

struct fancy_pants
{
    // doesn't transfer ownship, ensure foo stays alive
    fancy_pants(foo&);
};

Now it's clear I need to make sure the foo I pass it doesn't go out of scope. This didn't require the uglification of my code. If I'm going to write documentation, it should be written by me, describing rationale, intended usage, "gotcha"'s , examples, etc. Like Boost.

That said, all my headers have a copyright block on the top. I find this is a fantastic place to write a tiny bit of info about the class. For example, is_same.hpp:

/*-------------------------------------------------------
                    <copyright notice>

Determine if two types are the same. Example:

template <typename T, typename U>
void do_something(const T&, const U&, bool flag);

template <typename T, typename U>
void do_something(const T& t, const U& u)
{
    do_something(t, u, is_same<T,U>::value);
}

---------------------------------------------------------*/

It gives a quick demo at a glance. Anything more, like what I said above, is in a written documentation file.

But you see, I get to make up my code standards for the most part. At companies, you usually have to follow their standard anyway.

I'd stick to the Visual C++ Documentation Tags MSDN recommends. I see MSDN as the official documentation.

Example:

/// <summary>Sorts the list to by the given column</summary>
/// <param name="sel">Column to be sorted (index-1-based) and sort direction (pos. = ascending)</param>  
/// <returns>Documentation of return type</returns>  
void CExamlist::SetSorting(int sel) { ... }

Gets interpreted by ReSharper C++ to

Visual Studio 2012+ will interpret those comments as well according to How to write C++ comments that show up in Intellisense?

CppTripleSlash is a great free VS plugin that adds the correct XML tags after you type "///". This feature is ported from Visual Studio's C# editor.

You can follow the Google Style for commenting.

Types of things to mention in comments at the function declaration:

• What the inputs and outputs are.
• For class member functions: whether the object remembers reference arguments beyond the duration of the method call, and whether it will free them or not.
• If the function allocates memory that the caller must free.

• Whether any of the arguments can be NULL.

• If there are any performance implications of how a function is used.

• If the function is re-entrant. What are its synchronization assumptions?

Nothing will be "officially" supported because there's no company behind C++.

As you can see, doxygen support a lot of different blocks. Read: Documenting the code.

I personnaly prefer to stay close to other other recommendations. I try to stay near javadoc best practices.

Apart from Google Standards I found this guide here by Edward Parrish to be very useful!

For example block comments:

/**
    CS-11 Asn 2
    checks.cpp
    Purpose: Calculates the total of 6 checks

    @author Ed Parrish
    @version 1.1 4/10/16 
*/

or function code comments:

/**
    Encodes a single digit of a POSTNET "A" bar code.

    @param digit the single digit to encode.
    @return a bar code of the digit using "|" as the long
    bar and "," as the half bar.
*/

Its less verbose than doxygen and keeps it minimal. You can check the link for further details.