function prototyping

Printable View

12-26-2008
el_chupacabra

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); [..]
12-26-2008
transgalactic2

you should write it with the type of the variable
like you did on the first example
12-26-2008
kermit

The second example is legal, though the first example self-documents...
12-27-2008
dwks

http://cpwiki.sourceforge.net/Don%27...arameter_names
12-27-2008
root4

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...
12-27-2008
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.

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.
12-27-2008
laserlight

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?
12-27-2008
cas

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.
12-27-2008
laserlight

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.
12-27-2008
cas

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.
12-27-2008
whiteflags

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.
12-28-2008
Elysia

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++.
12-29-2008
root4

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.
12-29-2008
laserlight

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.
12-29-2008
Elysia

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.
12-29-2008
rpet

I never use variable names in function prototypes.
They are very helpful in man pages and other documentation, but program != documentation.

The concept of prototypes was invented to tell the compiler that a function with a specific signature exists.
So I don't see why we should use it for documentation purposes.
12-29-2008
Elysia

Do you want to ignore everything that has been stated so far?
It is good programming practice!
12-29-2008
laserlight

Quote:

Originally Posted by rpet

They are very helpful in man pages and other documentation, but program != documentation.

Have you never considered the school of thought that a program's source code should be as self-documenting as feasible? It is related to Abelson and Sussman's dictum that "programs must be written for people to read, and only incidentally for machines to execute".
12-29-2008
rpet

Quote:

Do you want to ignore everything that has been stated so far?
It is good programming practice!

Not in my opinion.

Quote:

Have you never considered the school of thought that a program's source code should be as self-documenting as feasible?

The "correct" level of documentation depends on the programmer, its coding abilities, experience and taste. Example: Hungarian Notation makes the code undoubtedly more self-documenting. Do you use it?

I think there is something like "too much" in-code documentation, a point where your code begins to be less readable the more stuff you add. This point is an individual thing, however. For me, it starts with parameters in function prototypes.
12-29-2008
Elysia

I understand your reluctance and unwanting to add certain things. However, good programming practices come before personal taste. So what, exactly, do you disagree with the facts outlaid before, except your individual opinion that it is "too much" documentation and that it makes it less readable?
I wish I could say it is an individual opinion, but that too, can cause problems. We have a member on the board who prefers global variables over local despite it being bad practice, and so everyone reacts if that someone recommends global variables over local. And I can imagine that someone making it a mess for co-workers to maintain the code, as well.
12-29-2008
whiteflags

Quote:

I think there is something like "too much" in-code documentation, a point where your code begins to be less readable the more stuff you add. This point is an individual thing, however. For me, it starts with parameters in function prototypes.

So what do you do? I assume you document the function somewhere, some way usually. If you haven't yet, you should learn, in case you ever collaborate or work as a programmer.
12-29-2008
laserlight

Quote:

Originally Posted by rpet

Example: Hungarian Notation makes the code undoubtedly more self-documenting. Do you use it?

The type-based "Systems" Hungarian notation generally does not make code more self-documenting, especially where variables are declared near first use, since the types in the declaration are the documentation. The purpose/semantics-based "Apps" Hungarian notation does make code more self-documenting, but I generally do not use it since I prefer to spell out the semantic information with proper words, where feasible.

Quote:

Originally Posted by rpet

I think there is something like "too much" in-code documentation, a point where your code begins to be less readable the more stuff you add. This point is an individual thing, however. For me, it starts with parameters in function prototypes.

I can agree with your general sentiment, but how do parameter names in function prototypes make the code less readable? I can only see it being a potential danger, as mentioned by root4, where the parameter names in the function definition are changed but the prototypes are not changed correspondingly. However, this danger can apply to documentation of any kind.
12-29-2008
rpet

Quote:

However, good programming practices come before personal taste.

Good programming practice is a matter of personal taste - nothing more. The more people agree with a specific practice the more it is considered "good", no matter if it's really useful or not.
12-29-2008
Elysia

No, it is not. If that were true, would using global variables be good programming practice if you thought it was OK?
No, that is not the case. Good programming practice is a set of guidelines that are agreed upon by a majority of good programmers who know what they speak of.
12-29-2008
laserlight

Quote:

Originally Posted by rpet

Good programming practice is a matter of personal taste - nothing more. The more people agree with a specific practice the more it is considered "good", no matter if it's really useful or not.

Nah, that's "standard practice" :D By definition, "good programming practice" means that it has to be actually useful. Unfortunately, "good programming practice" is not always "standard practice", and vice versa.
12-29-2008
whiteflags

Quote:

Originally Posted by rpet

Good programming practice is a matter of personal taste - nothing more. The more people agree with a specific practice the more it is considered "good", no matter if it's really useful or not.

Well again, how do you document your functions? If we're going to discuss the issue in terms of who's right or wrong, then you might as well show us the level of documentation you find acceptable. We may end up agreeing.
12-29-2008
rpet

Quote:

No, it is not. If that were true, would using global variables be good programming practice if you thought it was OK?

There is a difference between variable names in function prototypes and the usage of global variables.
I said, the variable names are of no use, not that global variables are good.

Quote:

Unfortunately, "good programming practice" is not always "standard practice", and vice versa.

This is so true.

Quote:

If we're going to discuss the issue in terms of who's right or wrong, ...

That's exactly what I want to avoid.

Quote:

when you might as well show us the level of documentation you find acceptable. We may end up agreeing.

I don't think a function prototype is the best place to document a functions behaviour. I prefer "man strcpy" over "less /usr/include/string.h".
12-29-2008
Elysia

Quote:

Originally Posted by rpet

There is a difference between variable names in function prototypes and the usage of global variables.
I said, the variable names are of no use, not that global variables are good.

And I mentioned it is about programming practices. Just because you say names in prototypes are bad does not make it any less good programming practice.

Quote:

I don't think a function prototype is the best place to document a functions behaviour. I prefer "man strcpy" over "less /usr/include/string.h".

Names are not meant to be an all-out guide. They are meant to guide, not explain everything.
You have managed to avoid all the arguments for names in prototypes, only stating that you prefer this or prefer that, which goes against all the arguments put before you and earlier in the thread. And yet you refuse to say why.
And if you do not say why, I think that it is best if you keep your opinion to yourself and your own code, and not code that are shared.
Not everyone is like you, either. I do not have to type anything extra to get the list of parameters of a function. I only have to do something extra when first learning how to call a function.

Also, this is a discussion forum. We are supposed to discuss things. Putting in an opinion and not clarifying when asked is not much of a discussion if you ask me.
12-29-2008
whiteflags

Quote:

I don't think a function prototype is the best place to document a functions behaviour.

I prefer to document near the definition myself, so I would agree with your statement. However the point is that you should do it somewhere if you are doing anything remotely nontrivial/serious. Don't be a butthole and not document your work when you're writing a program for someone else. It's not helpful to anyone else they might hire, and your work has to be redone rather than simply maintained. I'm certain you see the efficiency in that.

Quote:

I prefer "man strcpy" over "less /usr/include/string.h".

That's convenient for the standard. When you work for a company, the hard documentation is often revised after the implementation. It won't always be relevant when you're working.

That said, you should at least write a comment detailing the interface.

Code:

/* Compute the area of a rectangle. PRE-CONDITION: length is assigned and width is assigned. POST-CONDITION: return value is the area. */ double rectArea(long length, long width);

And now you see the real value in nameds parameters. Because they match the documentation, their position and purpose is almost immediately clear while you are working. And that is important, because C uses position matching for argument lists.
12-29-2008
rpet

Quote:

We are supposed to discuss things. Putting in an opinion and not clarifying when asked is not much of a discussion if you ask me.

Sorry, I thought I clarified it already.

Adding a variable name to a function prototype is optional. The compiler does not care about it, so we cannot say if it is right or wrong. Each programmer has to decide if he uses it or not. I don't.

The #1 (and only) PRO-argument is the additional piece of documentation that we get when we see a prototype like this:

int rectarea(int width, int height);

It's true, but this information is already available in the function's definition, and (hopefully) in the documentation. Duplicating it is not necessary and that reason is good enough for me to avoid it. I don't write "if ((i == 0) == true)" either. The idea is to get rid of redundant code whenever possible.
12-29-2008
Elysia

True, but what if you forget what arguments it takes or what order?
Myself, I cannot remember exactly what or in what order arguments must be passed. But when typing out the function name, I clearly see what the arguments names are and thus I can pass the correct arguments and in order.
It is more of a reminder than actual documentation, but it is very helpful. And sometimes it even makes it so that I do not need to read the documentation.
This is the main purpose of putting names in prototypes according to me. Is that a waste of space?
You do need those prototypes anyway, so copy and paste is easier.

I also take shortcuts with not typing out stuff too, but not at such a point where it becomes unreadable. In my opinion, stripping the names of the parameters in prototypes reduces readability. And therefore, I do not do it.
Usually, readability comes before duplicate / unnecessary code.
12-31-2008
dwks

Quote:

// ..._t suffix is reserved nervermind, this is an example

I think it's only reserved by POSIX, not ANSI. http://bytes.com/groups/c/668814-usi...fixes-typedefs
Nevertheless, it's probably a good idea to avoid it. I usually use the suffix "_type_t" myself. :p
(This is going to start another debate about naming conventions, I just know it.)

FWIW, here's what I think. I agree with Elysia here in that I think parameter names should be included in prototypes (otherwise I wouldn't have linked to the wiki page in the first place). I think it makes them easier to read, because your eye is used to parsing function definitions, and why should prototypes be any different?

Named parameters are also useful in distinguishing two variables of the same type. While I realize that this information can be found in source code as well, it's often much easier to find a header file than a source file.

I also think that there's no really good reason to remove the variable names. I mean, most of the time the prototype is just copied and pasted from the definition, or vise versa, at least in my code. I don't think it's unnecessary duplication, because it can be useful and it doesn't usually involve any extra effort on the part of the programmer.

Most of this has already been said before, I know; I just thought I'd chime in with my opinion. :)
12-31-2008
root4

About _t:

Quote:

I think it's only reserved by POSIX, not ANSI

Indeed, more references for those interested:
http://www.gnu.org/software/libtool/...ved-Names.html
http://www.opengroup.org/onlinepubs/...chap02_02.html