function prototyping

This is a discussion on function prototyping within the C Programming forums, part of the General Programming Boards category; Which is the de facto standard, the social rule if you will for function prototyping? I'm using gcc 4.0.0. Either ...

  1. #1
    Registered User
    Join Date
    Apr 2008
    Posts
    4

    Question 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);
    
    [..]

  2. #2
    Banned
    Join Date
    Oct 2008
    Posts
    1,535
    you should write it with the type of the variable
    like you did on the first example

  3. #3
    ... kermit's Avatar
    Join Date
    Jan 2003
    Posts
    1,528
    The second example is legal, though the first example self-documents...

  4. #4
    Frequently Quite Prolix dwks's Avatar
    Join Date
    Apr 2005
    Location
    Canada
    Posts
    8,046
    dwk

    Seek and ye shall find. quaere et invenies.

    "Simplicity does not precede complexity, but follows it." -- Alan Perlis
    "Testing can only prove the presence of bugs, not their absence." -- Edsger Dijkstra
    "The only real mistake is the one from which we learn nothing." -- John Powell


    Other boards: DaniWeb, TPS
    Unofficial Wiki FAQ: cpwiki.sf.net

    My website: http://dwks.theprogrammingsite.com/
    Projects: codeform, xuni, atlantis, nort, etc.

  5. #5
    Registered User
    Join Date
    Apr 2008
    Posts
    395
    I agree the full version (with varnames) is the 'recommended' one, but I would like to comment the arguments of the link posted above:

    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

    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)

    [...]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...

  6. #6
    cas
    cas is offline
    Registered User
    Join Date
    Sep 2007
    Posts
    975
    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.

  7. #7
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    21,414
    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?
    C + C++ Compiler: MinGW port of GCC
    Version Control System: Bazaar

    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  8. #8
    cas
    cas is offline
    Registered User
    Join Date
    Sep 2007
    Posts
    975
    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.

  9. #9
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    21,414
    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.
    C + C++ Compiler: MinGW port of GCC
    Version Control System: Bazaar

    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  10. #10
    cas
    cas is offline
    Registered User
    Join Date
    Sep 2007
    Posts
    975
    Quote Originally Posted by laserlight View Post
    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.

  11. #11
    Registered User whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    7,627
    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. #12
    C++まいる!Cをこわせ! Elysia's Avatar
    Join Date
    Oct 2007
    Posts
    22,428
    To your counter-arguments, pro-arguments:

    Quote Originally Posted by root4 View Post
    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.

    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.

    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 View Post
    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.

    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.

    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 Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

  13. #13
    Registered User
    Join Date
    Apr 2008
    Posts
    395
    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.


    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.

  14. #14
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    21,414
    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.
    C + C++ Compiler: MinGW port of GCC
    Version Control System: Bazaar

    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  15. #15
    C++まいる!Cをこわせ! Elysia's Avatar
    Join Date
    Oct 2007
    Posts
    22,428
    Quote Originally Posted by root4 View Post
    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.

    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.
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

Page 1 of 3 123 LastLast
Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Getting an error with OpenGL: collect2: ld returned 1 exit status
    By Lorgon Jortle in forum C++ Programming
    Replies: 6
    Last Post: 05-08-2009, 08:18 PM
  2. Seg Fault in Compare Function
    By tytelizgal in forum C Programming
    Replies: 1
    Last Post: 10-25-2008, 03:06 PM
  3. In over my head
    By Shelnutt2 in forum C Programming
    Replies: 1
    Last Post: 07-08-2008, 06:54 PM
  4. Including lib in a lib
    By bibiteinfo in forum C++ Programming
    Replies: 0
    Last Post: 02-07-2006, 01:28 PM
  5. Dikumud
    By maxorator in forum C++ Programming
    Replies: 1
    Last Post: 10-01-2005, 06:39 AM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21