Variable Names in C Function Prototypes: Not a Good Idea

It seems that some neophyte C programmers are unaware that variable names are not required (let alone not desired) in function prototypes. This also seems to happen when lazy programmers cut-and-paste the function head from the .c to the .h file and neglect to edit out the names.

The most obvious problem with this practice is that the names will need to be maintained in two separate files and can very easily get out of sync. Another is the general clutter the additional identifiers will create in the header files.

It is also poor documentation style to document a function twice, and variable names are a form of documentation--at least to those who pay attention to cultivating good documentation practices. This would be akin to providing a book with both footnotes at the bottom of each page and chapter notes at the end of each chapter containing redundant information. And what's worse still, is that the documentation process of code is usually integral with the programming of it: since the definitions are undergoing rapid changes during the process while the prototypes are relatively stable, the two tend to diverge significantly.

In addition to the maintenance nightmares caused by using variable names in two places, one must critically examine the purposes of the documentation, to whom it is addressed, and where the addressee goes to find it. The purposes will not be discussed here, but we do need to take a look at the last two. Documentation is addressed typically to clients and developers. The former will typically look to the manuals (either electronic or print media). To suggest they look in the header files is absurd--e.g. how many users of stdio.h look in that file for information on how to use printf()? Of course the developers would naturally document a function where it is defined rather than prototyped.

QED