Best practices: Where should function comments go in C/C++ code?

Question

So... I understand this might be subjective, but I'd like some opinions on what the best practice for this is.

Say I have the following header and .cpp file:

header:

// foo.h

class foo
{
public:
    int bar(int in);
};

cpp:

// foo.cpp

int foo::bar(int in)
{
    // some algorithm here which modifies in and returns the modified value
}

Now say I have this function comment:

/* 
    input:    an integer as input to algorithm foo

    output:   The result of the algorithm foo on input in

    remarks:  This function solves P = NP
*/

---

Would best practice be to place this function comment in the header above the function declaration or above the function definition in the cpp file? Thanks SO

Answer 1

I put comments describing what the function does in the header and comments describing how it does it in the cpp file.

Answer 2

I tend to use doxygen's format as function comments in the header file, allowing for programmers who peek in to learn more.

/**
 * Fills the handler with GIF information
 * 
 * @param filename GIF File name to be loaded
 * @return Inited GIF Handler or NULL for error
 */
pGifHandler gifHandlerLoad(const char* filename);

/**
 * Removes all data used by the GIF handler
 * 
 * @param gifHandler GIF Handler to be destroyed
 * @note This also clears palette and bitmap(s)
 */
void gifHandlerDestroy(pGifHandler gifHandler);

Programmers who wants to know how a certain function does it job, should peek into the .cpp file which would be commented on how it achieves it's goal.

Answer 3

Put function comments in the header file. That (apart from the manual) is the first place where users of your class will look for documentation. They do not care about the implementation, just about the interface.

Answer 4

Personally I'd prefer to put it above the implementation. I'd also use Doxygen style as it gives the same info but generates documentation.

It doesn't really matter though, especially if you go on to build seperate documentation with doxygen. Go with what YOU prefer.

Answer 5

Placing the comments in the header is a better solution. This is because:

• When looking for the documentation on a function, the header is the first place to check.
• The source file may not be available.
• The source file contains a lot more than function declaration, and the useful comments may get drowned.

Answer 6

I use Doxygen and use a short one-line description in the header and a beefy multi-line description in the implementation file. I think this yields cleaner header files that are easier on my eyes.

Note: If you were releasing this code as a library, people might not want to dig into the implementation. However, header files are usually fair game. In this case, I would put detailed documentation in the header.

header:

// foo.h

class foo
{
public:
    /**\brief This function solves P = NP */
    int bar(int in);
};

cpp:

// foo.cpp

/** 
 \param[in]    an integer as input to algorithm foo

 \returns    The result of the algorithm foo on input in
*/
int foo::bar(int in)
{
    // some algorithm here which modifies in and returns the modified value
}

Answer 7

I like to use PRE / POST conditions. None of the mentioned answers are wrong. Just what do you / company prefer. But PRE and POST conditions tell you what are the incoming / outgoing variables and how they are used. It also ensures that you are following some sort of guideline on how you are going to invoke the function (pre conditions) and what are the out puts after this function (post conditions).

Answer 8

Purpose in header, contract above function implementaiton, why's in function body.

That requries to either deliver .cpp, or to use a tool like doxygen to publish the documentation.

Advantage during dependencies: improving documentation will not affect header dependencies.

Anyway, choose a style, and be consistent

Answer 9

In general, comments should be dealt with in a similar manner to code separation -- interface-related comments (such as your example) would go in the header, whereas implementation-related comments would be better suited for the .cpp file.

If someone were to include your classes into their own programs, they should be able to get enough information from the header file to know how to use the class without having to break into the implementation itself. Header comments in excess of that are probably unnecessary and just serve to clutter out the useful information.

Answer 10

Best practice is whatever the standard is for the organization for which the code is written.

If it's just for me:

Function purpose and usage in the header, function details in the implementation.

Answer 11

Because I have always used Visual Assist X, and have the ability to jump around code very easily, I use the header file as an index. That is, the header file contains only the relevant data with no additional comments as not to add bloat to the file. If the reader wants further information on the function they can jump to the cpp.

This of course assumes that all people that read your code will have the same thought process, which is false. It is nice to only have bloat in one file though.

Answer 12

It's like asking what the best practices for putting your socks on is. Some tools have a better chance to work if you put the declaration and comment together and that probably makes the most sense as to what people expect. But commenting randomly is pointless. Having in/out stuff especially, unless you have a tool which uses that. Any programmer can see what he or she needs from the declaration, and same applies to the language in general. Nothing is more useless than comments like //this is the constructor.

Rather try to keep the code itself as simple as possible with names that make sense and a general organization to the code and if there is anything strange write a real paragraph about it like //We had to do this because some weird api we use requires certain things //that caused some other things to break and calls to it get optimized out sometimes //so don't take out these method calls or the optimizer optimizes out //some other stuff and the whole program stops working

Answer 13

In order of importance:

1. If it is part of an existing project and there is a prevailing comment style, use that. Consistency within a code base is more important than individual developer preference.

2. If it's a new project, use Doxygen or similar to document your code. Although that doesn't answer your question since you can use both styles with it. Run it nightly so that you have up-to-date browsable source documentation.

3. Personally, I prefer to put only brief one-line summary of in-line functions and members in header files, as otherwise it makes it harder to get a brief overview of the class functionality when skimming through the header file. Detailed descriptions I leave for the .cpp file. Some accessors I don't comment if their purpose is really obvious.

I also have a big pet peeve about lazy comments, especially one-liners:

e.g. This comment is a waste of space and might as well be deleted:

/** Get the width */
double getWidth();

This comment is useful:

/** Get the width in inches excluding any margin. */
double getWidth();

Answer 14

Inside the function, you can put the comment on the same line as the opening brace.

/* what is this function for, and so on.  Stuff the caller needs to know. */
foo ()
{       // pre-condition
}

I've seen that recommended as a location for listing pre-conditions. I've tried that, and found it fairly cramped, because I tend to write verbose comments. Also, the pre-condition is something the caller needs to be aware of, and it shouldn't get lost inside the function body.

Otherwise, I always try to put overall descriptions of the function outside it, and explanations of why it's coded the way it is inside the function, next to the code. So generally agreeing with the Doxygen promoters' style.