Sim Sim - 18 days ago 6
C++ Question

Should function declarations include parameter names?

What would you actually consider a better coding style: declaring the parameter names of functions/methods inside the header, or only in the source file, as it is possible to do both? If you actually consider declaring parameter names of functions/methods only in the source file, how would you then declare default values?

Outside header:

//One.hpp
#ifndef ONE_HPP
#define ONE_HPP
namespace eins {

/** \brief description
*
* \param one represents ....
* \param two represents ....
*/
void function(int,int);

}
#endif

// One.cpp
#include "One.hpp"

eins::function(int one,int two) {
//Do stuff//
}


Inside header:

//One.hpp
#ifndef ONE_HPP
#define ONE_HPP
namespace eins {

/** \brief description
*
* \param one represents ....
* \param two represents ....
*/
void function(int one,int two);

}
#endif

// One.cpp
#include "One.hpp"

eins::function(int one,int two) {
//Do stuff//
}


My personal point of view is that the first way is better, as the user is actually forced to read the comments/API and cannot be misguided to just read the parameter names. But I am not sure about this and actually declaring default values would break my style as you have to do that in the header declaration of a function/method.

Answer

While both are a-okay and used quite a lot, there is a distinct advantage to using parameter names in the declarations in your header files.

Most documentation systems (say, doxygen) will parse your header files and generate docs. As an example, look here: http://libface.sourceforge.net/doc/html/classlibface_1_1_face.html

Look at the constructor documentation.

Compare this

Parameters:
    x1  X coordinate of the top left corner of the face.
    y1  Y coordinate of the top left corner of the face.
    x2  X coordinate of the bottom right corner of the face.
    y2  Y coordinate of the bottom right corner of the face.
    id  ID of the face. -1 not not known.
    face    A pointer to the IplImage with the image data. 

and this

Parameters:
    param1  X coordinate of the top left corner of the face.
    param2  Y coordinate of the top left corner of the face.
    param3  X coordinate of the bottom right corner of the face.
    param4  Y coordinate of the bottom right corner of the face.
    param5  ID of the face. -1 not not known.
    param6  A pointer to the IplImage with the image data. 

You get the point. :)

Comments