function prototyping

Which is the de facto standard, the social rule if you will for function prototyping?

I'm using gcc 4.0.0. Either way, the compiler doesn't complain and the program gives the correct results.

If it's the same apparently, what are the pros and cons of each approach?


This one way

Code:

---


#include <stdio.h>
#include <math.h>

float area_sq(float side); //-->include var side and rad
float area_cir(float rad);

[..]

---

or this one?

Code:

---

#include <stdio.h>
#include <math.h>

float area_sq(float); //-->just declared I'll be using a float var in the future
float area_cir(float);

[..]

---

you should write it with the type of the variable
like you did on the first example

The second example is legal, though the first example self-documents...

http://cpwiki.sourceforge.net/Don%27...arameter_names

I agree the full version (with varnames) is the 'recommended' one, but I would like to comment the arguments of the link posted above:

Quote:

---

Anyone had who reads the prototype will have no idea what kind of parameters it takes

---

indeed, but if the types are named explicitly (typedef rules), this is much less true

Quote:

---

Some tools, such as Microsoft's IntelliSense parses the prototypes to give additional information[...]

---

I strongly disagree with this one: tools must be adapted to data, not the opposite, this is the same thing than adding directives to the beginning of a source file to tell the editor how it should highlight the syntax (e.g. emacs), I think this is really stupid (but this is my point of view)

Quote:

---

[...]is to copy the function head and paste it and use it as a prototype, as well. If then the programmer proceeds to strip the names of the parameters, that incurs extra work

---

I would have said otherwise: I hate to duplicate anything (because as any programmer knows, maintenance is duplicated and this is bad(tm), in this case if an argument name changes for instance, the prototype must be fixed too, and the signature itself rarely changes I think) so the shorter, the better...

This was just to balance the arguments for each side of the problem :)

In all cases, this is a time waste, the best method would be, obviously, to generate the interface from the corresponding source code, but it doesn 't seem to be the practice right now...

If you're writing a header file that will be installed system-wide, then you need to be careful. I would emphatically recommend not naming your parameters in such a header, but if you do, make sure you do it in such a way that the names won't clash with the user's namespace.

Since you don't want to clash with the implementation's namespace either, that leaves few options. One is to comment out the name:

Code:

---

int mylib_func(int /*param*/);

---

This documents what the parameter is without stepping on anybody's toes. Presumably, for this example, the user has been told not to use the prefix mylib_ so you could do:

Code:

---

int mylib_func(int mylib_param);

---

This, of course, technically does tread on the user's namespace, but it's his own fault if he uses your library without paying attention to your documentation.

This is a real issue; I've had to modify headers that used generic names for parameters because of the problems they created. If you're worried about a nameless parameter not being self-documented properly, then use comments! That's what they're there for.

Quote:

---

Originally Posted by cas

If you're writing a header file that will be installed system-wide, then you need to be careful. I would emphatically recommend not naming your parameters in such a header, but if you do, make sure you do it in such a way that the names won't clash with the user's namespace.

---

The problem seems remote though, since local names hide global names. Macro names will cause a problem, but then if the naming convention of fully capitalised macro names is used this will be a remote problem too.

Quote:

---

Originally Posted by cas

This is a real issue; I've had to modify headers that used generic names for parameters because of the problems they created. If you're worried about a nameless parameter not being self-documented properly, then use comments! That's what they're there for.

---

How exactly did this happen?

Quote:

---

How exactly did this happen?

---

It probably was a macro issue. I don't remember specifics, because it's only happened a couple of times and it was a while ago at that. I just have not-so-fond memories of digging through headers in /usr/include or /usr/local/include, removing a parameter name.

Quote:

---

Originally Posted by cas

It probably was a macro issue. I don't remember specifics, because it's only happened a couple of times and it was a while ago at that. I just have not-so-fond memories of digging through headers in /usr/include or /usr/local/include, removing a parameter name.

---

hmm... then it seems to me that the advice should not be about avoiding parameter names and/or trying to carefully name them to avoid name collision, but about avoiding macros and/or trying to carefully name them to avoid name collision.

Quote:

---

Originally Posted by laserlight

hmm... then it seems to me that the advice should not be about avoiding parameter names and/or trying to carefully name them to avoid name collision, but about avoiding macros and/or trying to carefully name them to avoid name collision.

---

The only realistic method would appear to be your suggestion of using uppercase for macros. But the problem with that is that there are times when you (or I, at least) don't want your macros to be shouting out that they are macros. In my experience uppercase identifiers mean "danger!" That is, you've got what you think is a function, but it's really a macro so it might have unexpected side-effects, etc. On other occasions, I've used macros that are as safe as functions, so I don't need to announce their presence. This is, I suppose, one of those matters of taste.

Ideally users needn't look inside of headers anyway. I would consider a library defective if its only documentation was the names of its functions, etc. Most times when I've looked into headers to try to figure out a library, I ended up looking at the source code. A simple named parameter doesn't necessarily tell its valid range of values, for example.

In my experience, macros are usually capitalized because they are supposed to shout "CONSTANT!" rather than "danger!"

Whereas macro functions are capitalized because they are macros. It's a matter of consistency, really. If you use macros to a point that you start forgetting that they are macros, then I defy you and claim that they should announce their presence. At any rate, with this type of problem, it's a failure of the programmer and not the language.

To your counter-arguments, pro-arguments:

Quote:

---

Originally Posted by root4

indeed, but if the types are named explicitly (typedef rules), this is much less true

---

But this is about the names of the parameters, not the types! You see the types either way.

Quote:

---

I strongly disagree with this one: tools must be adapted to data, not the opposite, this is the same thing than adding directives to the beginning of a source file to tell the editor how it should highlight the syntax (e.g. emacs), I think this is really stupid (but this is my point of view)

---

Yes, you are indeed right. However, no tools are psychic. If you do not tell or write out some information, how is it to guess?
In this case, the tool is conforming to you - you do not have to write pragmas or comments to make it work.

Quote:

---

I would have said otherwise: I hate to duplicate anything (because as any programmer knows, maintenance is duplicated and this is bad(tm), in this case if an argument name changes for instance, the prototype must be fixed too, and the signature itself rarely changes I think) so the shorter, the better...

---

Often when working with functions, you often change what parameters it takes rather than their names. Plus even if you change the names, when you are finished with it, you can just copy it and use it as a prototype instead of manually writing it out and/or changing it. Less work.
Of course, if there are tools for this, all the better.

Quote:

---

Originally Posted by cas

If you're writing a header file that will be installed system-wide, then you need to be careful. I would emphatically recommend not naming your parameters in such a header, but if you do, make sure you do it in such a way that the names won't clash with the user's namespace.

---

This is nonsense. Macros should never interfere with parameter names. If they do, it is the macros fault. They should never really have been invented. There should be other, safer, ways to use copy and paste rather than replace everything it sees.

Quote:

---

Since you don't want to clash with the implementation's namespace either, that leaves few options. One is to comment out the name:

Code:

---

int mylib_func(int /*param*/);

---

This documents what the parameter is without stepping on anybody's toes. Presumably, for this example, the user has been told not to use the prefix mylib_ so you could do:

Code:

---

int mylib_func(int mylib_param);

---

This, of course, technically does tread on the user's namespace, but it's his own fault if he uses your library without paying attention to your documentation.

---

No, the first one is bad. It is better than nothing, but it may be ignored by information tools.
And while a developer should indeed read the documentation before use, intellisense may help you remember what arguments goes where for example! That is why it also is so good to see the parameter names.

Quote:

---

This is a real issue; I've had to modify headers that used generic names for parameters because of the problems they created. If you're worried about a nameless parameter not being self-documented properly, then use comments! That's what they're there for.

---

I disagree on that one.
The purpose is to allow information tools, as well as readability.
Use proper macro names (upper case), or undef and redef the macros before and after the prototypes.

As well, in C++, macros should be avoided, and prototypes apply to C as well as C++.

Quote:

---

But this is about the names of the parameters, not the types! You see the types either way.

---

No more debate, but a quick example to illustrate what I meant:

instead of:

Code:

---

int some_function(uint8_t ip_address[4]);

---

you could name explicitly the type:

Code:

---

int some_function(ipv4_address_t); // ..._t suffix is reserved nervermind, this is an example

---

in which case, the formal parameter name becomes redundant and useless.

Quote:

---

However, no tools are psychic. If you do not tell or write out some information, how is it to guess?

---

Please, I know there is no magic in computer science... the tool should simply be able to find the information where it exists (in the implementation files, instead of the interface files, for the problem at hand). The rule is simply to not constrain the user: whoever is right concerning the fact of indicating the argument names in prototypes, no tool should force the user to use a particular option, that's all. Your compiler is kind enough to let you use any indentation format, right? same thing here.

Quote:

---

Originally Posted by cas

Ideally users needn't look inside of headers anyway. I would consider a library defective if its only documentation was the names of its functions, etc. Most times when I've looked into headers to try to figure out a library, I ended up looking at the source code. A simple named parameter doesn't necessarily tell its valid range of values, for example.

---

I certainly would prefer if Doxygen/Javadoc type of comments were included with a programming interface, and even better yet, if the generated documentation was already available. However, as you note, this is an ideal. It may still be useful that a user is always able to quickly check the header and get at least a rough understanding of how to use the function in question.

Quote:

---

Originally Posted by root4

you could name explicitly the type:

---

Yes, such abstraction is generally a Good Thing, and not only where parameters are concerned. However, where parameters are concerned, it is still reasonable that a function may have more than one parameter of the same type, in which case the names would still be useful in clarifying their individual purpose.

Quote:

---

Originally Posted by root4

No more debate, but a quick example to illustrate what I meant:

instead of:

Code:

---

int some_function(uint8_t ip_address[4]);

---

you could name explicitly the type:

Code:

---

int some_function(ipv4_address_t); // ..._t suffix is reserved nervermind, this is an example

---

in which case, the formal parameter name becomes redundant and useless.

---

I see what you mean now. However, it still leaves us in the dark of the type. Especially when it comes to pointers.
Parameter names are a quick way to nudge your memory - to remember what to put where after checking the documentation. For this purpose, both type and names are necessary.
For all I know, I could just create something of type ipv4_address_t and scratch me head when it does not work.
For all I want to say is - do not presume what the programmer wants or does. Give the programmer the best tools and information there is and let him/her make the best out of it.

Quote:

---

Please, I know there is no magic in computer science... the tool should simply be able to find the information where it exists (in the implementation files, instead of the interface files, for the problem at hand). The rule is simply to not constrain the user: whoever is right concerning the fact of indicating the argument names in prototypes, no tool should force the user to use a particular option, that's all. Your compiler is kind enough to let you use any indentation format, right? same thing here.

---

This quickly becomes a mess, however. There would be 100s of tools with 100s of different formats. Which format to use? And where would it find it? In the source files or some external file? It quickly becomes a big complexity. So the easiest common middle ground is to put names of parameters in headers - as programmers have done for years.

But I do agree with you that it is an ideal tool. Still, it does not solve the problem with maintaining the prototypes, unless it automatically generates them from the source.