Prototype parameter names

Question

In my header, I have a prototype declaration like this:

void move(int, int);

I can omit the parameter names, that's how I'm used to it from C. I do that so that I don't have to keep the parameter names in sync - it's extremely confusing if they differ between prototype and implementation.

Right now, I'm documenting all of my code with Doxygen, and I decided to put all comments into the header. Now I have to refer to parameter names that are defined in the implementation but not in the header: I find that confusing.

/**
 * Moves the entity to the specified point.
 * @param x The x coordinate of the new position.
 * @param y The y coordinate of the new position.
 */
void move(int, int);

In the generated Doxygen HTML, it is not easy to figure out which parameter is which. Of course, one could follow the same order here, but if one has many parameters, it is still confusing.

The alternative would be to duplicate parameter names and try to keep them in sync. However, some people don't encourage this approach, saying that header parameters should start with a double underscore so that the user of a method can not possibly use the same name (names starting with __ are disallowed in C++).

How do you do it?

Answer 1

It is a terrible idea to not name the parameters in the header if it is not clear what that parameter is for. The header should be the documentation for your code, so that someone trying to use it can avoid reading the implementation. As you found, it's pointless to document the parameters by name and then not tell the user which is which. That's not to say that they must match, but in the header they should be meaningful for the users of your code. In the implementation, choose the name that is best for you. E.g. it would be totally feasible to have:

.h:

void move(int x, int y);

.cpp:

void move(int deltaX, int deltaY)
{
   ...

The only times that it would make sense (if you care about other programmers using your code) to elide the parameter names is when it is bone crushingly obvious what that parameter does. E.g.

void SetNumPotatoes(int);
void EnableLights(bool);
void InitFoo(Foo&);

// but then...
T& GetItem(int);  // probably obvious enough, but does typing 'index' kill you?
void DoSomething(bool, float, int);  // someone using this will say, "WTF?"