Should function declarations include parameter names? [closed]

Answer 1

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.

Answer 2

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

Answer 3

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.

Answer 4

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.