Should function declarations include parameter nam

2019-01-25 04:02发布

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.

4条回答
劳资没心,怎么记你
2楼-- · 2019-01-25 04:40

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. :)

查看更多
混吃等死
3楼-- · 2019-01-25 04:40

My rule of thumb is to name everything. Not every header file has nice comments before each function, and therefore the parameter name is all that remains to decipher the function when there is a lack of decent documentation.

In the worst-case, it's a bit of extra typing on the behalf of the programmer. It shows intent, in addition to any comments that have been provided. I have never, ever been one to advocate a practice that seems to exist purely to save typing. In these days of auto-complete iDEs, it's never been easier to be verbose.

查看更多
你好瞎i
4楼-- · 2019-01-25 04:48

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.

Root(大扎)
5楼-- · 2019-01-25 04:50

You ought to strive to name your functions well enough that they do not need to include the parameter name to be clear as to what they do. If you see a method prototype:

void save(const std::string&);

what is it doing? Is it saving that string? Or is it saving to a filepath represented by the string? Or...?

So you could do:

void save(const std::string& filepath);

to clarify. But this only clarified when someone is looking to at the header. If instead you do:

void saveToFilepath(const std::string&);

it should be quite clear everywhere. Of course, as you add more paramters, this becomes more cumbersome (but is one more reason to not add too many parameters; see Bob Martin's Clean Code on that; he commends nullary and unary functions, is hesitant about binary functions, quite reticent about trinary functions, and unwilling for any more than that).

So my advice is strive to not have a reason to include your parameters names in your function headers, not so much as an end in itself (though I am all for every bit of reduced duplication and increased brevity) but as a heuristic for how well you are naming your functions. (Note that if you are working with legacy code, you may want to cut yourself slack—but with the end goal in mind.)

This approach means that you will have to stop and think every time you type in a function header to check yourself, rather than following a black-and-white rule about whether to include the parameter names. Programmers tend to prefer to charge ahead rather than stopping to think about things like naming, but stopping to reflect is valuable on many different levels.

In sum, strive to not need to include the parameter names in the headers; and when you don't need them, don't bother to include them, for brevity and reduced duplication.

查看更多
登录 后发表回答