Should Function Declarations Include Parameter Names

Should function declarations include parameter names?

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

Why should you give parameters names in function declaration?

Function declarations describe the interface, i.e. how the function is meant to be used. Consider the following example:

void rotate(int x, int y);

as opposed to:

void rotate(int height, int width);

These declarations have the same number and type of parameters, but the semantics of the parameters are very different. Naming the parameters is a reasonable way of expressing this meaning.

---

Of course, one could make the argument that the function should be either:

void rotate(Point);

or

void rotate(Dimensions);

where both Point and Dimensions are simple structs containing 2 ints. This approach does make naming the parameters in the declaration unnecessary.

While this is probably the better approach, this may not always be an option. For example, if you are working on a large code base that has many uses of such functions, this might require a lot of refactoring, and the cost of that might not be justified by the benefits.

For new code, I would personally recommend this approach, not just for the clear semantics in the declaration, but more for the added type safety provided by wrapping the arguments in a separate type.

---

There are pros and cons to both approaches, and which one you pick is an engineering and design decision that should be made based on the particular use case, and circumstances.

Why do function prototypes include parameter names when they're not required?

No, these are not necessary, and are mostly ignored by the compiler. You can even give them different names in different declarations; the following is entirely legal:

int foo(int bar);
int foo(int biz);
int foo(int qux) {
    ...
}

(The compiler does check that each name is used only once in the same argument list: int foo(int bar, int bar); is rejected.)

The reason to put them in is documentation:

• If someone reads your header file, they can tell at a glance what each parameter is used for.
• If you use a fancy IDE, it can show you the parameter names when you begin typing the function call.
• Documentation tools like Doxygen can parse the parameter names and show them in the documentation.

Function pointer with named arguments?

The names of arguments in a function pointer are optional, just as the names of arguments in a function declaration are optional. This is because parameter names if given are not used, so both formats are allowed.

In section 6.7.6.3 of the C standard regarding Function Declarators, which includes both function prototypes and function pointers, paragraph 6 states:

A parameter type list specifies the types of, and may
declare identifiers for, the parameters of the function.

The only place where function parameters require a name is in the actual definition of a function.

For a function definition, Section 6.9.1p5 states:

If the declarator includes a parameter type list, the
declaration of each parameter shall include an identifier, except
for the special case of a parameter list consisting of a single
parameter of type void , in which case there shall not be an
identifier. No declaration list shall follow.

---

Related Topics