As I understand it, in a function declaration there is no need to give variable names, but it is still recommended.
For example: the setcur() function accepts two parameters : row number and
and column number.Hence can be declared as follows:
void setcur(int, int);
void setcur(int row, int col);
Why is it recommended to give variable names in a function declaration?
It really is more for readability sake. You only really need the variable type in the function declaration; however, it is good for someone reading your code to understand what these inputs actually are, assuming your name them something appropriate.
It will make your life a lot easier if you are working on a large file and you don't remember what your function in your .h file takes in as input.
Adding a decent variable name improves readability and helps documenting your function. Consider e.g.
void area(int, int); // which parameter comes first? area of what?
vs
void area(int radius, int height); // now it's clear that it is a cylinder, order is also clear
You may also want to use e.g. doxygen to generate the documentation automatically, in which case you usually document the header files. In that case, it makes sense to name the function parameters, so they correspond to the names of the doxygen's \params.
There's been significant discussion here if you're really curious:
Why do function prototypes include parameter names when they're not required?
The short answer is readability, but to use your example, basically
void setcur(int,int);
can be implemented as
(1) void setcur(int row,int col);
or
(2) void setcur(int col,int row);
(any other implementations are possible, but allow 2 as an example).
With the variable names in the header, you can easily get a sense of what to pass for row and col. Otherwise you need to dig into the code file which may exist separate from the header. Imagine if all you had was
void setcur(int, int)
and assumed (1), but it really was (2). You would have a hard to debug failure in your code.
While the names are not technically required, they serve as documentation to help the user. Also, they help your IDE to show better signatures, completions, etc.
Adding documentation in some tool-aware form might look like an alternative, but your code might also be used with different IDEs and, unlike comments, the variable names in the declarations are the only standardized way of providing more semantic information in the declaration of a function.
Also note that in case of libraries, the user of the library might not even see the definition of the function, all he has is the header file with the declaration and a binary library to link against.
Related
I have a C header file containing various declarations of functions, enums, structs, etc, and I hope to extract all declared function names into a boost.preprocessor data structure for iteration, using only the C preprocessor.
All function declarations have two fixed distinct macros around the return type, something like,
// my_header.h
FOO int * BAR f(long, double);
FOO void BAR g();
My goal is to somehow transform it into one of the above linked boost.preprocessor types, such as (f, g) or (f)(g). I believe it is possible by cleverly defining FOO and BAR, but have not succeeded after trying to play around with boost.preprocessor and P99.
I believe this task can only be done with the preprocessor as,
As a hard requirement, I need to stringify the function names as string literals later when iterating the list, so runtime string manipulation or existing C++ static reflection frameworks with template magic are out AFAIK.
While it can be done with the help of other tools, they are either fragile (awk or grep as ad-hoc parsers) or overly complex for the task (LLVM/GCC plugin for something robust). It is also a motivation to avoid external dependencies other than those strictly necessary i.e. a conforming C compiler.
I don't think this is going to work, due to limitations on where parentheses and commas need to occur.
What you can do, though, is the opposite. You could make a Boost.PP sequence that contains the signatures in some structured form and use it to generate the declarations as you showed them. In the end, you have the representation you want as well as the compiler's view of the declarations.
After some closer look at the internals of preprocessor tricks, I believe this is theoretically impossible. This answer is kind of a more detailed expansion on top of #sehe's nice answer.
The fundamental working principle of arbitrary preprocessor lists like those in boost.preprocessor is indirect recursion. As such, it requires a way to consume one argument and pass the remaining on. The only two ways for CPP are commas (which can separate arguments) and enclosing parentheses (which can invoke macros).
In the case of f(int, long), f is neither followed by a comma nor surrounded by a pair of parenthese, so there is no way for it to be separated from the following list by the preprocessor without knowing the name in advance.
It could have changed the game if there were a BAZ after f, but sadly there is not and I have no control over the said library header :(
There are other issues, albeit not as fatal, such as the UB of having preprocessor directives within macro definition or arguments.
Perhaps someday it would become possible to leverage the reflection TS to get all declared function names within a namespace as a consteval compile-time list and then iterate it with something along the lines of constexpr for, all in a semantic and type-safe manner... who knows
From a class exercise:
Fill in the blanks to print
"it works!" on the screen,
type in the function
prototype before its call.
void some_func();
int main()
{
some_func();
return 0;
}
void some_func() {
cout << "it works!" << endl;
}
If I am using the function right after I declared it, why did this code define it in the end?
I mean, we could just have declared and defined and then call in the main.
I don't get the point of declaring, calling and then defining.
I have just started learning about functions. I am a beginner.
EDIT from perspective of C.S. teacher: This student is wondering about the purpose of function prototypes generally. This is a typical case of teaching a concept with an example that is simple enough to master, yet so simple it doesn't yet serve a purpose. Perhaps it is still not the right question for StackOverflow, but should at least be closed for the right reason. It is a very common and well-defined question.
It is perfectly fine to put the definition before the use in most cases. The only time the C language requires you to put a non-definition declaration before use is when two or more functions use each other, so one or more of them have to be declared before the others can be defined. I prefer building up a module from smaller/lower parts to larger parts, so I generally put function definitions before the routines that use them. However, the teacher may be presenting this exercise to teach concepts about declarations, not to teach you to use a particular style.
If you have not yet learned about them, you will soon learn about header files. As programs grow more complicated, we no longer want to keep all the source code in one file, for several reasons. (It becomes more difficult to manage more code. Grouping functions by some type of service they provide or some sort of common data they work with can help us organize the source code and keep it more sensible to human understanding. It also makes it easier to reuse functions in other programs.) Once we break a program up into separate source files, some definitions will no longer be in the same source file as routine to use them. So, instead of definitions, we put declarations in the source files as necessary. A routine foo defined in one source file, and other files that use it will have declarations of foo.
This brings up a problem that declarations are then repeated in many places. That becomes a burden to maintain—any time the definition of foo is changed, all the declarations of it have to be changed. And it is easy to make mistakes, which can bugs in the program, because declaring a function differently from how it is defined can cause undesired behavior. To deal with this, declarations for one set of things, typically all those defined in one source file (and intended to be used by other source files), are gathered into one file, called a header file and typically given a name ending in .h. Then other source files merely include the header files that contain the declarations they need, using an #include directive that tells the compiler to include contents the header file in the current compilation as if it were a part of the current source file.
Because of this, you must learn about various ways declarations can be used, including putting them before functions that use the declared functions.
(I would include C++, but its declarations can be more complicated.)
This question already has answers here:
Closed 10 years ago.
Possible Duplicate:
Should function declarations include parameter names?
In a C++ header file, you need to give the function prototype's name, return type and arguments' types. You need not specify the names for the arguments.
Example:
double fraction(double numerator, double denominator);
vs
double fraction(double, double);
Is there an advantage in writing an argument's name? Readability?
Is there any difference for compiling, or for efficiency, or else?
No difference in compilation. (May be parsing of later will be fast as it has to parse less code, but who cares about that?).
The big advantage is in readability. In second case how can the user differentiate between which is numerator and which is denominator?
The main reason for keeping the argument names in the header file is for consistency and readability. If you have a policy of removing them then you can no longer copy/paste the declarations from your cpp file.
If you're using a documentation engine like doxygen, that might also provide you a cogent reason to keep parameter names since documentation engines tend to parse headers and will provide nicer output if you've included the names of the parameters.
Other than this, there is no strict reason to keep them.
No difference in efficiency. Omitting the name in header should be synced with omitting it in implementation file. There you can omit it, if your impl does not use that arg, and then everybody can see by looking at the parameter-list wether an arg is used or not (And some compilers give warning when an arg has a name, but isn't used in implementation. Hope that helps...
As you said, you put them there so someone looking at the header understands the purpose of those parameters.
Just had a 'Fundamentals of Programming' lecture at uni and was told that the convention for using/declaring functions is to have the main() function at the top of the program, with functions/procedures below it and to use forward declarations to prevent compiler errors.
However, I've always done it the other way - functions at top main() at bottom and not using forward declarations and don't think I've ever seen it otherwise.
Which is right? Or is it more a case of personal preference? Some clarification would be hugely appreciated.
It's up to you. Personally, I keep main on bottom because the times when I have other functions in there, it's either just one or two other little functions or a code snippet.
In real code, you'd have hopefully split your project up (having multiple "unrelated" functions in a file is bad) and so main would likely be nearly alone in the file. You'd just #include the things main needs to get things going and use them.
There could be the case when your functions are related to each other. If you simply write them above the main() without forward-declaration you have to order them so they'll know the functions they depend on. In some cases (circular references) it won't even be possible to compile without forward declaration.
When forward declaring the functions you won't run into this issue.
Additionally when having main() as first function, you'll produce more readable code, but thats perhaps just personal preference.
It could also be more readable cause another coder has on overview about the functions he'll find in the file.
If there is a standard, it's to have the function declarations in a .h file which is included. That way, it doesn't matter what the order of functions in the file is. I almost never write functions without a declaration, and it takes me aback when other people do.
The standard most professional C++ developers use is this.
two files per class: the header file (named e.g., Class.h), which only declares all of the class' data members and functions; and the implementation file (named Class.cpp in the same example), containing only implementations of those functions.
the main function (if your solution has it) goes into a file named, e.g. Main.cpp all by itself.
It is OK to put multiple classes or even the entire program into one file when you work on small-scale home or school projects. Because of the small scale, it doesn't really matter how you order the classes or the functions. You can do what is more convenient to you. But if your professor requires students to follow certain code standards for homework (e.g. put main() first), then you have to follow those standards.
This approach is most likely favoured by your professor and most likely the reason she's teaching it as convention. There are two options here, go with the flow (i.e. don't try to disrupt and potentially get marked down for stuff because your professor feels that you're not following "convention") or explain to her - there is no requirement to do it this way (or any other way), as long as the intention of the code is clear!
The advice to have declarations (function prototypes) is more related to C then to C++, because in C++ there are no implicit function declarations, so you must always declare before use. Therefore you will definitely have at least one function declaration which is not definition if you have a recursion involving more then one function.
For a small project use whatever style you want but be consistent.
For a large project you'll probably need several .cpp files and have the interfaces (be they classes or functions) defined in the header files. Also be consistent at least within a single file.
And the last thing, have I said to be consistent?
I normally use the second form because you have to maintain function declarations - they must have the right signature and name, and imo, they're just excessive typing when you could just define the functions first. No maintenance, no wasted time.
I think the principle that applies here is "Don't Repeat Yourself". If you use a forward declaration, you're repeating yourself unnecessarily.
In C++, declaration and definition of functions, variables and constants can be separated like so:
function someFunc();
function someFunc()
{
//Implementation.
}
In fact, in the definition of classes, this is often the case. A class is usually declared with it's members in a .h file, and these are then defined in a corresponding .C file.
What are the advantages & disadvantages of this approach?
Historically this was to help the compiler. You had to give it the list of names before it used them - whether this was the actual usage, or a forward declaration (C's default funcion prototype aside).
Modern compilers for modern languages show that this is no longer a necessity, so C & C++'s (as well as Objective-C, and probably others) syntax here is histotical baggage. In fact one this is one of the big problems with C++ that even the addition of a proper module system will not solve.
Disadvantages are: lots of heavily nested include files (I've traced include trees before, they are surprisingly huge) and redundancy between declaration and definition - all leading to longer coding times and longer compile times (ever compared the compile times between comparable C++ and C# projects? This is one of the reasons for the difference). Header files must be provided for users of any components you provide. Chances of ODR violations. Reliance on the pre-processor (many modern languages do not need a pre-processor step), which makes your code more fragile and harder for tools to parse.
Advantages: no much. You could argue that you get a list of function names grouped together in one place for documentation purposes - but most IDEs have some sort of code folding ability these days, and projects of any size should be using doc generators (such as doxygen) anyway. With a cleaner, pre-processor-less, module based syntax it is easier for tools to follow your code and provide this and more, so I think this "advantage" is just about moot.
It's an artefact of how C/C++ compilers work.
As a source file gets compiled, the preprocessor substitutes each #include-statement with the contents of the included file. Only afterwards does the compiler try to interpret the result of this concatenation.
The compiler then goes over that result from beginning to end, trying to validate each statement. If a line of code invokes a function that hasn't been defined previously, it'll give up.
There's a problem with that, though, when it comes to mutually recursive function calls:
void foo()
{
bar();
}
void bar()
{
foo();
}
Here, foo won't compile as bar is unknown. If you switch the two functions around, bar won't compile as foo is unknown.
If you separate declaration and definition, though, you can order the functions as you wish:
void foo();
void bar();
void foo()
{
bar();
}
void bar()
{
foo();
}
Here, when the compiler processes foo it already knows the signature of a function called bar, and is happy.
Of course compilers could work in a different way, but that's how they work in C, C++ and to some degree Objective-C.
Disadvantages:
None directly. If you're using C/C++ anyway, it's the best way to do things. If you've got a choice of language/compiler, then maybe you can pick one where this is not an issue. The only thing to consider with splitting declarations into header files is to avoid mutually recursive #include-statements - but that's what include guards are for.
Advantages:
Compilation speed: As all included files are concatenated and then parsed, reducing the amount and complexity of code in included files will improve compilation time.
Avoid code duplication/inlining: If you fully define a function in a header file, each object file that includes this header and references this function will contain it's own version of that function. As a side-note, if you want inlining, you need to put the full definition into the header file (on most compilers).
Encapsulation/clarity: A well defined class/set of functions plus some documentation should be enough for other developers to use your code. There is (ideally) no need for them to understand how the code works - so why require them to sift through it? (The counter-argument that it's may be useful for them to access the implementation when required still stands, of course).
And of course, if you're not interested in exposing a function at all, you can usually still choose to define it fully in the implementation file rather than the header.
The standard requires that when using a function, a declaration must be in scope. This means, that the compiler should be able to verify against a prototype (the declaration in a header file) what you are passing to it. Except of course, for functions that are variadic - such functions do not validate arguments.
Think of C, when this was not required. At that time, compilers treated no return type specification to be defaulted to int. Now, assume you had a function foo() which returned a pointer to void. However, since you did not have a declaration, the compiler will think that it has to return an integer. On some Motorola systems for example, integeres and pointers would be be returned in different registers. Now, the compiler will no longer use the correct register and instead return your pointer cast to an integer in the other register. The moment you try to work with this pointer -- all hell breaks loose.
Declaring functions within the header is fine. But remember if you declare and define in the header make sure they are inline. One way to achieve this is to put the definition inside the class definition. Otherwise prepend the inline keyword. You will run into ODR violation otherwise when the header is included in multiple implementation files.
There are two main advantages to separating declaration and definition into C++ header and source files. The first is that you avoid problems with the One Definition Rule when your class/functions/whatever are #included in more than one place. Secondly, by doing things this way, you separate interface and implementation. Users of your class or library need only to see your header file in order to write code that uses it. You can also take this one step farther with the Pimpl Idiom and make it so that user code doesn't have to recompile every time the library implementation changes.
You've already mentioned the disadvantage of code repetition between the .h and .cpp files. Maybe I've written C++ code for too long, but I don't think it's that bad. You have to change all user code every time you change a function signature anyway, so what's one more file? It's only annoying when you're first writing a class and you have to copy-and-paste from the header to the new source file.
The other disadvantage in practice is that in order to write (and debug!) good code that uses a third-party library, you usually have to see inside it. That means access to the source code even if you can't change it. If all you have is a header file and a compiled object file, it can be very difficult to decide if the bug is your fault or theirs. Also, looking at the source gives you insight into how to properly use and extend a library that the documentation might not cover. Not everyone ships an MSDN with their library. And great software engineers have a nasty habit of doing things with your code that you never dreamed possible. ;-)
Advantage
Classes can be referenced from other files by just including the declaration. Definitions can then be linked later on in the compilation process.
You basically have 2 views on the class/function/whatever:
The declaration, where you declare the name, the parameters and the members (in the case of a struct/class), and the definition where you define what the functions does.
Amongst the disadvantages are repetition, yet one big advantage is that you can declare your function as int foo(float f) and leave the details in the implementation(=definition), so anyone who wants to use your function foo just includes your header file and links to your library/objectfile, so library users as well as compilers just have to care for the defined interface, which helps understanding the interfaces and speeds up compile times.
One advantage that I haven't seen yet: API
Any library or 3rd party code that is NOT open source (i.e. proprietary) will not have their implementation along with the distribution. Most companies are just plain not comfortable with giving away source code. The easy solution, just distribute the class declarations and function signatures that allow use of the DLL.
Disclaimer: I'm not saying whether it's right, wrong, or justified, I'm just saying I've seen it a lot.
One big advantage of forward declarations is that when used carefully you can cut down the compile time dependencies between modules.
If ClassA.h needs to refer to a data element in ClassB.h, you can often use just a forward references in ClassA.h and include ClassB.h in ClassA.cc rather than in ClassA.h, thus cutting down a compile time dependency.
For big systems this can be a huge time saver on a build.
Disadvantage
This leads to a lot of repetition. Most of the function signature needs to be put in two or more (as Paulious noted) places.
Separation gives clean, uncluttered view of program elements.
Possibility to create and link to binary modules/libraries without disclosing sources.
Link binaries without recompiling sources.
When done correctly, this separation reduces compile times when only the implementation has changed.