Menu
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.
420
In a prototype, parameter names are optional (and in C/C++ have function prototype scope, meaning their scope ends at the end of the prototype), however, the type is necessary along with all modifiers (e.g. if it is a pointer or a reference to const parameter) except const alone.
The function declarator includes the list of parameters that can be passed to the function when it is called by another function, or by itself. In C++, the parameter list of a function is referred to as its signature. The name and signature of a function uniquely identify it.
Arguments are passed by value; that is, when a function is called, the parameter receives a copy of the argument's value, not its address. This rule applies to all scalar values, structures, and unions passed as arguments. Modifying a parameter does not modify the corresponding argument passed by the function call.
For example, if the my_function() function, discussed in the previous section, requires two integer parameters, the declaration could be expressed as follows: return_type my_function(int x, y); where int x, y indicates that the function requires two parameters, both of which are integers.
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. :)
188
Include the parameter names in the declarations.
It is best to provide other developers as much information as you can in as compact a format as you can. Forcing them to look up to the comments to determine something simple like what the parameters are is likely to take them out of the flow, make them less productive, and piss them off.
32
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With
