Thread: function prototyping

  1. #16
    Registered User
    Join Date
    Oct 2001
    Posts
    62
    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.

  2. #17
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    Do you want to ignore everything that has been stated so far?
    It is good programming practice!
    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.

  3. #18
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    27,929
    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".
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  4. #19
    Registered User
    Join Date
    Oct 2001
    Posts
    62
    Do you want to ignore everything that has been stated so far?
    It is good programming practice!
    Not in my opinion.

    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.

  5. #20
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    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.
    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.

  6. #21
    Lurking whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    9,616
    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.

  7. #22
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    27,929
    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.
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  8. #23
    Registered User
    Join Date
    Oct 2001
    Posts
    62
    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.

  9. #24
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    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.
    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.

  10. #25
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    27,929
    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" 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.
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  11. #26
    Lurking whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    9,616
    Quote Originally Posted by rpet View Post
    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. #27
    Registered User
    Join Date
    Oct 2001
    Posts
    62
    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.

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

    If we're going to discuss the issue in terms of who's right or wrong, ...
    That's exactly what I want to avoid.

    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".

  13. #28
    C++まいる!Cをこわせ!
    Join Date
    Oct 2007
    Location
    Inside my computer
    Posts
    24,654
    Quote Originally Posted by rpet View Post
    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.

    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.
    Last edited by Elysia; 12-29-2008 at 09:17 AM.
    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.

  14. #29
    Lurking whiteflags's Avatar
    Join Date
    Apr 2006
    Location
    United States
    Posts
    9,616
    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.

    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.
    Last edited by whiteflags; 12-29-2008 at 09:24 AM. Reason: grammar fixes

  15. #30
    Registered User
    Join Date
    Oct 2001
    Posts
    62
    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.

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, 02:28 PM
  5. Dikumud
    By maxorator in forum C++ Programming
    Replies: 1
    Last Post: 10-01-2005, 06:39 AM