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

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.