A Little Advice in Making C Header File

Home / A Little Advice in Making C Header File

A Little Advice in Making C Header File

October 19, 2015 | Article | No Comments

As we know, C and C++ programming language are supporting modular programming. It means that we can break our long code into several separate modules. For this we need a file named header file that mostly are set of function prototypes. Later the functions will be implemented on another source file. Now, what are things we should (or should not) put in header file? When we should create a header file?

This article will give little advice about what we should include in our header file. This list is based on personal experience, so you can agree or reject it.

[DO] Always Create “guard” Macro for Each Header

What is “guard” that I mean? They are 3 line of code that protect your header files from multiple inclusion. This is essentially important as we can include our header as many as we like but compiler only read it once. Therefore, we can guarantee that our declarations are only once. The “guard” are composed by macro #ifndef, #define, #endif. You must check a unique macro name that acts as you unique header identifier. If not exist, we declare our code. Otherwise, the compiler will ignore the declaration. Our code will be between #define and #endif code respectively.

[DO] Create One Header File for Each “Module” of the System

Yes, for each. A module may comprise one or more compilation units. But it should implement just one aspect of the system. Examples of well-chosen modules are:

  • device driver for A/D converter
  • communication protocol
  • alarm manager that is responsible for logging error conditions and alerting the user.

Every module must be create on one header file.

[DO] Include All of the Function Prototypes for Public Interface of Module

For example, a header file lcd.h might contain function prototype for lcd_init(), lcd_write(), and lcd_clear(). But private implementation or helper functions that only known or used by those functions must be remain hidden.

[DON’T] Include Any executable Lines of Code in a Header file, Including Variable Declarations.

It’s not so effective. Another reason is there would be a chance of fatal error by multiple declaration. Especially if you are not providing “guard” for header files. But it is necessary to make an exception for the bodies of some inline functions.

[DON’T] Expose Any Variable in Header File

Again! If you want to make a variable public or known by another module, it’s not wise to put them on header file. Use extern in header file while the actual declaration would be in source code file (.c file).

[DON’T] Expose Internal Format of Any Module-Specific Data Structure Passed to or Returned from One or More of the Module’s Interface Functions

No declaration of structure in header file. Implicitly, no “struct { … } foo;” like code in any header file. If you do have a type that you need to pass in and out of your module so client can create instance of it, simply use “typedef struct moduleb_type” in header type. Outside that module should never know the internal format of the struct.

Maybe this is strict, but I hope this advice will give a better and readable C programming practice. More advice would be added later.

,

About Author

about author

xathrya

A man who is obsessed to low level technology.

Leave a Reply

Your email address will not be published. Required fields are marked *

Social media & sharing icons powered by UltimatelySocial