1. Summary
  2. Files
  3. Support
  4. Report Spam
  5. Create account
  6. Log in

Do not remove parameter names

From cpwiki

Jump to: navigation, search

Don't omit parameter names.

When writing a function prototype, there is a minimalist approach, like this.

void* binsearch(const void* , void*, size_t, size_t, Function);

Then you would copy everything to the left of the semicolon over to where you define the function, and add in parameter names there, otherwise the code could not compile. While this is legal, doing the minimum will only tell the programmer who wants to use the function the order and type of the parameters. It lets the compiler do its job, but the purpose of the arguments aren't conveyed. Consequently, it takes the more time (and perhaps trial and error) to understand how this function works.

The benefit of parameter names is to make documentation easier to follow.

typedef int (*Function)(const void*, const void*);
   const void* key - what to search for
   void* base      - the array 
   size_t nel      - the number of members of base
   size_t width    - the size of each member of base
   Function CompFunc-the comparison function

   Given base, find the element key. Returns a pointer to the first oc-
   currence of key, or NULL for a failed search. The base array should be
   sorted in ascending order with CompFunc. CompFunc is expected to have 2 
   arguments which point to the key, and a member of base, and to return an
   integer less than 0, 0, or greater than 0, if key is less than, equal 
   to, or greater than the member of base.
void* binsearch(const void* key, void* base, size_t nel, size_t width, Function CompFunc);

Without parameter names, the documentation for this function would be a challenge to write and to understand. The example function has a lot of arguments, and without parameter names, it's just that more difficult to reckon which pointer is which, or which size_t is which. In particular, void* pointers are very nondescript types that don't explain what to pass in, but that type of pointer is essential here. You would have to communicate in the docs what to pass in terms of argument 1 and argument 2, whereas good variable names represent themselves. Furthermore, many IDEs offer code-completion tools that can look up a function prototype on demand as the programmer writes code. In these cases, what is written in the prototype is what the programmer sees. The lack of information can lead to the programmer having to re-read the documentation for the function all over again.

Personal tools