- Use multiple .c files, not just one "main.c" file. Every .c file should have a set of variables and functions that are tightly related to each other, and only loosely related to the other .c files. "Main.c" should only have the main loop in it.
- .C files allocate storage and define executable code. Only .c files have a function defined in them. Only .c files allocate storage for variables
- .H files define external storage and define function prototypes The .h files give other modules the information they need to work with a particular .c file, but don't actually define storage and don't actually define code. The keyword "extern" should generally be showing up in .h files only.
- Every .c file should have a corresponding .h file. The .h file provides the external interface information to other modules for using the corresponding .c file.
Here is an example of how this works. Let's say you have files: main.c adc.c output.c process.c watchdog.c
main.c would have the main loop that polls the A/D converter, processes values, sends outputs, and pets the watchdog timer. This would look like a sequence of consecutive subroutine calls within an infinite loop. There would be a corresponding main.h that might have global definitions in it (you can also have "globals.h" although I prefer not to do that myself). Main.c would #include main.h, adc.h, output.h, process.h and watchdog.h because it needs to call functions from all the corresponding .c files.
adc.c would have the A/D converter code and functions to poll the A/D and store most recent A/D values in a data structure. The corresponding adc.h would have extern declarations and function prototypes for any other routine that uses A/D calls (for example, a call to look up a recent A/D value from polling). Adc.c would #include adc.h and perhaps nothing else.
output.c would take values and send them to outputs. The corresponding output.h would have information for calling output functions. Output.c would probably just #include output.h. (Whether main.c actually calls something in output.c depends on your particular code structure, but I'm assuming that outputs have two steps: process.c queues outputs, and the main.c call actually sends them.)
process.c would take A/D values, compute on them, and queue results for output. It might need to call functions in adc.c to get recent values, and functions in output.c to send results out. For that reason it would #include process.h, adc.h, output.h
watchdog.c would set up and service the watchdog timer. It would #include watchdog.h
One wrinkle is that some compilers can only optimize in a single .c file (e.g., only do "inline" within a single file). This is no reason to put everything in a single .c file! Instead, you can just #include all the other .c files from within main.c. (You might have to make sure you include each .h file once depending on what's in them, but often that isn't necessary.) You should avoid #including a .c file from within another .c file unless there is a compelling reason to do so such as getting your optimizer to actually work.
This is only intended to convey the basics. There are many hairs to split depending on your situation, but if you follow the above guidelines you're off to a good start.
NOTE: Michael Barr published another, compatible, take on this topic in May. I just saw it at: http://www.embedded.com/electronics-blogs/barr-code/4215934/What-belongs-in-a-header-file
I'd add to your rules:
ReplyDeleteEVERY .C must include its own .h.
This way the compiler works for you, spotting obvious inconsistencies between declarations in the header and body. It won't catch everything - but I've watched a colleague spent a week chasing down a bug caused by the header and body having different declarations for the prototype of a function. A good linker will sometimes help here - but not all linkers are good. In avoiding silly errors, we need all the help we can get.
#including your own header in your C body file just becomes a habit after a while - costs nothing, and every now and again saves you from weeks of torture.
I have seen it stated numerous times that the main.c files doesn't normally have a header. stating that it doesn't need to be declared to anything else. But that contradicts the suggestion that extern variables be declared in the header that corresponds to where they are defined so the compiler can check for a match in deceleration between the main.h and the main.c file. If I don't declare the extern in main.h and instead in for example lcd_functions.h then there can be a mismatch e.g. int in main and short int in lcd_functions. Plus I think I will have to declare it also in com_functions.h Can you clarify which header extern declarations should go in and why. Thanks
ReplyDeletelcd_functions.h should contain extern declarations for all the visible variables in lcd_functions.c. Main.c can then #include lcd_functions.h. In the general case, the compiler is not checking main.c vs. main.h, but rather it is checking main.c against all the .h declarations that main.c needs to touch.
ReplyDeleteThe important rule is that lcd_functions.h is NOT used to create the variables for lcd_functions.c. Variables are created/declared/initialized inside the .c file, and the .c file generally does not include its own .h file. The .h file is primarily for use by *other* .c files to get the interface information.
"
DeleteVariables are created/declared/initialized inside the .c file, and the .c file generally does not include its own .h file. The .h file is primarily for use by *other* .c files to get the interface information.
"
Thanks for your clear explanation, and I agree with the statement above very much.
Are there any cases lcd_functions.c should include lcd_functions.h?
In object oriented terms, the lcd_functions.c file defines the objects and methods, and the lcd_functions.h file provides the external interface used by other .c files.
ReplyDelete