Thread: Prototypes?

http://www.cppreference.com/stdstring/strstr.html

Code:

  #include <cstring>
  char *strstr( const char *str1, const char *str2 );

http://www.opengroup.org/onlinepubs/...ns/strstr.html

Code:

#include <string.h>

char *strstr(const char *s1, const char *s2);

I don't know. You tell me.

As you can tell, they didn't choose very meaningful names, but regardless of variable names, shouldn't documentation be consulted when using a function?

Not really. The entire purpose of having meaningful names is to make it unnecessary to consult the documentation every time you use the function. What I remember about strstr is "searches for a substring". The char* return type tells me that it returns a pointer to the found position. I wish the argument names would tell me where I put the needle and where the haystack.

I don't know. You tell me.

hmm... I get your point. The second prototype is identical to the version from C99.

On the other hand, C++03's version of std::find is:

Code:

template<class InputIterator, class T>
InputIterator find(InputIterator first, InputIterator last, const T& value);

It is a non-member function template, and so analogous to strstr(). Personally, I find that the C++ version is clearer: I get a hint on what are the parameters without having to look further into the text of the standard. With the C99 version, I must look further into the text of the standard. If you do not know what they do, then either way you have to read further, but if you only want to know the order of arguments, having descriptive parameter names looks good to me.

They do help. You may know a lot of functions and what they do, but sometimes you can forget what the parameters are and what they do. It's very easy to mix up source & destination and arguments that are like each other, for example.
All I see is bad practice for non-descriptive prototypes.

If the arguments have sensible names, then having the variable names there is a help. If they are just meaningless names (such as s1, s2 in the strstr() example above), then it makes little difference. Of course, if you use the method I do, which is to write the function first, then copy it to the prototype location, it's meaningless to go and edit the function prototype to REMOVE the names - but that's depending on how you go about producing the prototype in the first place.

--
Mats

Originally Posted by MacGyver

I don't know. You tell me.

http://msdn2.microsoft.com/en-us/lib...kz(VS.80).aspx

Code:

char *strstr(
   const char *str,
   const char *strSearch 
); // C only

first is a string, second is a substring. And it is shown by intellisense - I do not need to go to the external documentation if I know in general what function does (In VS2008 it is even clearer - _Str and _SubStr)

Nothing on MSDN is ever clear.