Should I put the includes in the header file or the source file? If the header file contains the include statements, then if I include that header file in my source, then will my source file have all of the included files that were in my header? Or should I just include them in my source file only?
Only put includes in a header if the header itself needs them.
Examples:
Your function returns type size_t. Then #include <stddef.h> in the header file.
Your function uses strlen. Then #include <string.h> in the source file.
There's been quite a bit of disagreement about this over the years. At one time, it was traditional that a header only declare what was in whatever module it was related to, so many headers had specific requirements that you #include a certain set of headers (in a specific order). Some extremely traditional C programmers still follow this model (religiously, in at least some cases).
More recently, there's a movement toward making most headers standalone. If that header requires something else, the header itself handles that, ensuring that whatever it needs is included (in the correct order, if there are ordering issues). Personally, I prefer this -- especially when the order of headers can be important, it solves the problem once, instead of requiring everybody who uses it to solve the problem yet again.
Note that most headers should only contain declarations. This means adding an unnecessary header shouldn't (normally) have any effect on your final executable. The worst that happens is that it slows compilation a bit.
Your #includes should be of header files, and each file (source or header) should #include the header files it needs. Header files should #include the minimum header files necessary, and source files should also, though it's not as important for source files.
The source file will have the headers it #includes, and the headers they #include, and so on up to the maximum nesting depth. This is why you don't want superfluous #includes in header files: they can cause a source file to include a lot of header files it may not need, slowing compilation.
This means that it's entirely possible that header files might be included twice, and that can be a problem. The traditional method is to put "include guards" in header files, such as this for file foo.h:
#ifndef INCLUDE_FOO_H
#define INCLUDE_FOO_H
/* everything in header goes here */
#endif
The approach I have evolved into over twenty years is this;
Consider a library.
There are multiple C files, one internal H file and one external H file. The C files include the internal H file. The internal H file includes the external H file.
You see that from the compilers POV, as it compiles a C file, there is a hierarchy;
external -> internal -> C code
This is the correct ordering, since that which is external is everything a third party needs to use the library. That which is internal is required to compile the C code.
If header file A #includes header files B and C, then every source file that #includes A will also get B and C #included. The pre-processor literally just performs text substitution: anywhere it finds text that says #include <foo.h> it replaces it with the text of foo.h file.
There are different opinions on whether you should put #includes in headers or source files. Personally, I prefer to put all #includes in source file by default, but any header files that cannot compile without other pre-requisite headers should #include those headers themselves.
And every header file should contain an include guard to prevent it being included multiple times.
Make all of your files so that they can be built using only what they include. If you don't need an include in your header remove it. In a big project if you don't maintain this discipline you leave yourself open to breaking an entire build when someone removes an include from a header file that is being used by a consumer of that file and not even by the header.
In some environments, compilation will be fastest if one only includes the header files one needs. In other environments, compilation will be optimized if all source files can use the same primary collection of headers (some files may have additional headers beyond the common subset). Ideally, headers should be constructed so multiple #include operations will have no effect. It may be good to surround #include statements with checks for the file-to-be-included's include-guard, though that creates a dependency upon the format of that guard. Further, depending upon a system's file caching behavior, an unnecessary #include whose target ends up being completely #ifdef'ed away may not take long.
Another thing to consider is that if a function takes a pointer to a struct, one can write the prototype as
void foo(struct BAR_s *bar);
without a definition for BAR_s having to be in scope. A very handy approach for avoiding unnecessary includes.
PS--in many of my projects, there will be a file which it's expected that every module will #include, containing things like typedefs for integer sizes and a few common structures and unions [e.g.
typedef union {
unsigned long l;
unsigned short lw[2];
unsigned char lb[4];
} U_QUAD;
(Yes, I know I'd be in trouble if I moved to a big-endian architecture, but since my compiler doesn't allow anonymous structs in unions, using named identifiers for the bytes within the union would require that they be accessed as theUnion.b.b1 etc. which seems rather annoying.
You should only include files in your header that you need to declare constants and function declarations. Technically, these includes will also be included in your source file, but for clarity sake, you should only include in each file the files you actually need to use. You should also protect them in your header from multiple inclusion thusly:
#ifndef NAME_OF_HEADER_H
#define NAME_OF_HEADER_H
...definition of header file...
#endif
This prevents the header from being included multiple times, resulting in a compiler error.
Your source file will have the include statements if your put it in the header. However, in some cases it would be better to put them in the source file.
Remember that if you include that header in any other sources, they will also get the includes from the header, and that is not always desirable. You should only include stuff where it is used.
Related
I'm writing a Pong game in C using ncurses. I placed function definitions for the ball, the player, and the AI opponent into ball.c, player.c, and ai.c respectively. Each of these files includes another file, pong.h, which contains function prototypes, structure definitions, and global variables. My main function is in pong.c, which provides the game loop and handles keypresses.
My project also includes a number of libraries: ncurses.h, stdlib.h, and time.h. Where should I include these libraries? Currently, they are included in pong.h, like so:
#ifndef _PONG_H
#define _PONG_H
#include <ncurses.h>
#include <stdlib.h>
#include <time.h>
/* everything else */
#endif
However, only certain files make use of functions in stdlib.h/time.h. This leads me to believe that it might make more sense to only include one-use libraries in the file where they are used. On the other hand, including all libraries in one place is more straightforward.
I'm wondering if there is a way to do this which is considered more conventional or efficient.
There is no firm rule, instead you should balance convenience and hygiene. You're already aware that the meta include is more convenient for your other .c files, but I'll emphasize some more obscure concerns with header files:
Putting dependencies (e.g. ncurses.h) in your public header files may make it more difficult to include your header file in other projects
The transitive costs of header files will dominate compile time, so reducing unnecessary includes will allow your project to compile more quickly. Programs have been developed to manage includes.
Header files can destructively interfere with each other, for instance because of macros that change the semantics of subsequently included header files. windows.h is probably the most notorious culprit, and the risks can be difficult to quantify for large header files or large sets of header files.
Over time it can become obvious what header files should actually be bundled, e.g. when the convenience benefit is high and the risks and costs are low. On a small project perhaps it is obvious from the outset.
Preferably, you should include the headers in the files that are actually using them even if it might be a little redundant. That way if later you remove an include to a header you defined, you can avoid compilation issues if that file happened to use stdio.h functions but didn't include it for itself.
It's also more clear at a glance of the first few lines what the file is using.
Suppose I have a code like this
foo.h
#pragma once
#ifndef _HEADER
#define _HEADER
//code
#endif
foo.c
#include "header.h"
//code
main.c
#include "foo.h"
int main() {
return 0
}
Why should I include foo.h in foo.c? It can still work without it.
You are correct that you do not HAVE to include the module's header file in the module's C file.
There are a few reasons why you may wish to do so. (What follows is a non-exhaustive list).
As others have noted, it helps ensure that the declarations in the header file are consistent with the definitions in the C file. This is of particular importance when some or all of the routines are to be called from another module. In other words, this can help cut down on errors.
It safely and quickly allows you a little extra flexibility in where you place the routines in the file. Granted this can be achieved with forward declarations in the C file, but if the routines are going to be called from another module, then save yourself the extra typing (and possible typos) and make use of the header file inclusion. Why would you want the flexibility? It allows you to group the routines as you see fit for both maintainability and readability.
It helps to keep your list of include files leaner and cleaner. Presumably, your module's header file will include anything that it needs. Therefore, including that header file means that you don't have to explicitly include all those extra header files. Experience has taught me that a modules with lean include lists often have fewer WTF moments (as well as having a very small positive impact on compilation time).
Hope this helps.
Lately I have been using header files to split up my program into separate files, (C files containing functions and header files declaring them). Every thing works fine but for some reason, I need to include <stdio.h> and <stdlib.h> in EVERY C file... or my project fails to compile. Is this expected behavior?
C modules need to know either how something is defined, or where it can find a definition. If the definition is in the header file, then you should include it in the modules that use it. Here is a link to information regarding header files.
The answer would depend on whether or not that functions might depend on other declared functions in other .c/.h files.
For example:
filea.c:
#include "filea.h";
methodA()
{
methodB();
}
fileb.c:
#include <somelibrary.h>
#include "fileb.h"
methodB();
{
somelibrarycode();
}
This will not compile unless filea.c includes the header for fileb.h as it has some external dependency that is not resolved.
If this is not what you're describing than there is some other spaghettification happening, or you accidentally statically typed functions preventing them from being seen outside of the .c file.
One possible solution to this problem is to have a single shared.h with all the other includes, but I personally don't recommend this as this merely masks the issue instead of making it readily apparently which files depend on what and establish clear lines of dependency.
They must be included some way.
Some projects require long list of includes in .c files, possibly with mandatory sort, even forcing assumption that no header includes any other header.
Some allow assuming some includes form some headers.
Some use collection headers (that include a list of small headers) and replace long lists with those.
Some go even further, using "forced header" option of compiler, so include will not appear anywhere, and declare the content to be implicitly assumed. It may go on project or whole codebase level, or combined. It plays pretty well with precompiled headers.
(And there are many more strategies, you get the figure, all with some pros&cons.)
So currently in my programming I now have a fairly large range of functions I have created and stored in separate C files that I use quite frequently from project to project.
My question is what is the simplest, most effective way to implement them into other projects? Currently I just make a header file for each new project that has the function prototypes for all the custom functions I want to use.
I then have every C file in the project include this "master" header. In this header I also include header files that each C file utilizes, so every C file has one header; let's just call it master.h.
I feel like I am doing this completely wrong. Should I be making header files for each C file and including them into a master header file? or should I just create header files per C file and include them as needed? If I do that how will everything still be linked together?
What is the best way to go about using header files in projects?
Do not have a header file including other header files. Let the .c file do that - makes compilation quicker.
Use forward declarations. Makes recompilation quicker as it does not need to open up other files and if any simple change the make command will spend ages compiling lots of stuff.
Group functions together in both a header file and the corresponding .c file if they logically fit together. For static libraries the linker picks out the appropriate bits. For dynamic libraries they are loaded at run time (hence can be used by other binaries) if not currently in memory.
Do not have a master.h. Just make libraries contain functions that are related (e.g. math function, input/output functions etc). The various projects can pick 'n' chose what they require.
I recommend against having a master.h file, as your whole project ends up being too coupled. Every time you change master.h all your source files need to be recompiled, which significantly slows down the build process. Instead, try to create .h files with related functions. The C library is a good inspiration for this: stdlib.h, math.h etc.
In order to use these headers, you should include them in each .c, just like you would with the standard C headers:
#include <math.h>
#include <stdio.h>
As for linking, this is a totally different subject. If most of your functions are inlined, you do not have to worry about linking. Otherwise, you should define them in .c files which are named similarly to your headers (e.g., utils.c for utils.h etc.)
Create a header file for all the .c files. Group the similar functions in a .c file. Dont forget to add header guard in each header files.
For example consider a header file one.h, it should contain the below header guards.
#ifndef ONE_H
#define ONE_H
//give your function prototypes here.
#endif //ONE_H
Header guard will be useful to avoid double includes.
I'm used to doing all my coding in one C file. However, I'm working on a project large enough that it becomes impractical to do so. I've been #including them together but I've run into cases where I'm #including some files multiple times, etc. I've heard of .h files, but I'm not sure what their function is (or why having 2 files is better than 1).
What strategies should I use for organizing my code? Is it possible to separate "public" functions from "private" ones for a particular file?
This question precipitated my inquiry. The tea.h file makes no reference to the tea.c file. Does the compiler "know" that every .h file has a corresponding .c file?
You should regard .h files as interface files of your .c file. Every .c file represents a module with a certain amount of functionality. If functions in a .c file are used by other modules (i.e. other .c files) put the function prototype in the .h interface file. By including the interface file in your original modules .c file and every other .c file you need the function in, you make this function available to other modules.
If you only need a function in a certain .c file (not in any other module), declare its scope static. This means it can only be called from within the c file it is defined in.
Same goes for variables that are used across multiple modules. They should go in the header file and there they have to marked with the keyword 'extern'. Note: For functions the keyword 'extern' is optional. Functions are always considered 'extern'.
The inclusion guards in header files help to not include the same header file multiple times.
For example:
Module1.c:
#include "Module1.h"
static void MyLocalFunction(void);
static unsigned int MyLocalVariable;
unsigned int MyExternVariable;
void MyExternFunction(void)
{
MyLocalVariable = 1u;
/* Do something */
MyLocalFunction();
}
static void MyLocalFunction(void)
{
/* Do something */
MyExternVariable = 2u;
}
Module1.h:
#ifndef __MODULE1.H
#define __MODULE1.H
extern unsigned int MyExternVariable;
void MyExternFunction(void);
#endif
Module2.c
#include "Module.1.h"
static void MyLocalFunction(void);
static void MyLocalFunction(void)
{
MyExternVariable = 1u;
MyExternFunction();
}
Try to make each .c focus on a particular area of functionality. Use the corresponding .h file to declare those functions.
Each .h file should have a 'header' guard around it's content. For example:
#ifndef ACCOUNTS_H
#define ACCOUNTS_H
....
#endif
That way you can include "accounts.h" as many times as you want, and the first time it's seen in a particular compilation unit will be the only one that actually pulls in its content.
Compiler
You can see an example of a C 'module' at this topic - Note that there are two files - the header tea.h, and the code tea.c. You declare all the public defines, variables, and function prototypes that you want other programs to access in the header. In your main project you'll #include and that code can now access the functions and variables of the tea module that are mentioned in the header.
It gets a little more complex after that. If you're using Visual Studio and many other IDEs that manage your build for you, then ignore this part - they take care of compiling and linking objects.
Linker
When you compile two separate C files the compiler produces individual object files - so main.c becomes main.o, and tea.c becomes tea.o. The linker's job is to look at all the object files (your main.o and tea.o), and match up the references - so when you call a tea function in main, the linker modifies that call so it actually does call the right function in tea. The linker produces the executable file.
There is a great tutorial that goes into more depth on this subject, including scope and other issue you'll run into.
Good luck!
-Adam
A couple of simple rules to start:
Put those declarations that you want to make "public" into the header file for the C implementation file you are creating.
Only #include header files in the C file that are needed to implement the C file.
include header files in a header file only if required for the declarations within that header file.
Use the include guard method described by Andrew OR use #pragma once if the compiler supports it (which does the same thing -- sometimes more efficiently)
To answer your additional question:
This
question precipitated my inquiry. The
tea.h file makes no reference to the
tea.c file. Does the compiler "know"
that every .h file has a corresponding
.c file?
The compiler is not primarily concerned with header files. Each invocation of the compiler compiles a source (.c) file into an object (.o) file. Behind the scenes (i.e. in the make file or project file) a command line equivalent to this is being generated:
compiler --options tea.c
The source file #includes all the header files for the resources it references, which is how the compiler finds header files.
(I'm glossing over some details here. There is a lot to learn about building C projects.)
As well as the answers supplied above, one small advantage of splinting up your code into modules (separate files) is that if you have to have any global variables, you can limit their scope to a single module by the use of the key word 'static'. (You could also apply this to functions). Note that this use of 'static' is different from its use inside a function.
Your question makes it clear that you haven't really done much serious development. The usual case is that your code will generally be far too large to fit into one file. A good rule is that you should split the functionality into logical units (.c files) and each file should contain no more than what you can easily hold in your head at one time.
A given software product then generally includes the output from many different .c files. How this is normally done is that the compiler produces a number of object files (in unix systems ".o" files, VC generates .obj files). It is the purpose of the "linker" to compose these object files into the output (either a shared library or executable).
Generally your implementation (.c) files contain actual executable code, while the header files (.h) have the declarations of the public functions in those implementation files. You can quite easily have more header files than there are implementation files, and sometimes header files can contain inline code as well.
It is generally quite unusual for implementation files to include each other. A good practice is to ensure that each implementation file separates its concerns from the other files.
I would recommend you download and look at the source for the linux kernel. It is quite massive for a C program, but well organised into separate areas of functionality.
The .h files should be used to define the prototypes for your functions. This is necessary so you can include the prototypes that you need in your C-file without declaring every function that you need all in one file.
For instance, when you #include <stdio.h>, this provides the prototypes for printf and other IO functions. The symbols for these functions are normally loaded by the compiler by default. You can look at the system's .h files under /usr/include if you're interested in the normal idioms involved with these files.
If you're only writing trivial applications with not many functions, it's not really necessary to modularize everything out into logical groupings of procedures. However, if you have the need to develop a large system, then you'll need to pay some consideration as to where to define each of your functions.