Thread: function prototyping

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

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

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.

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.

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.

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.

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.

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.

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.

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.