Strides Interactive

Poor header inclusion managementFiled Under: Weekly Tuesday Dose of goodness

Hi all,

While I’m still preparing the long list of instruction documentations, I’ve decided to add one article here which I think a lot of people either know about or are totally ignorant about.

This is about poor header management. For a start, let me just clarify what headers are we talking about here. It actually refers to 2 things.

1) C/C++ header files
2) Java class files

These 2 types of files have one thing in common. To know more, read on…

So what do they have in common?

Both type of files require an option to be set in order for them to work. Of course, header files affect the compilation process, while the class files affect the build process.

Either way, you’ll have to specify certain path settings to allow the respective processes to succeed. Let’s put the class files aside and talk about the header files first. Once I’ve explained the problem with header files, you’ll naturally understand the case for class files.

For header files, you’ll put a -I (for GCC compilers) or /I (for Visual Studio compilers) to add the header paths. Why do you need these options?

Now let’s take a look at a sample header file:

#include "header1.h"
#include "header2.h"
//so and and so forth

With this we assume that both headers are in the same directory as the sample header file. But most of the time, this isn’t the case.

Let’s assume that

sampleHeader.h is in c:\project\src\sample\
header1.h is in c:\project\src\utility\
header2.h is in c:\project\src\core

In order to make this project compilable, in your compilation options, there must be at least the following:

-Ic:\project\src\utility -Ic:\project\src\core

So if you have a lousy header management design, you’ll need to either place it here in a long line of -I commands or you’ll have to place it in the additional header files in the Visual Studio project or by setting the default header directories in the Visual Studio options. (The latter being a lousy choice as well)

For make files, it’s probably less a hassle simply because the makefile does everything for you. If you need another -I directory, simply add it into the list of include directories.

But that’s not the point.

By doing it this way, it encourages bad habits to form over time. Developers now think that they can just include without giving a care for the actual header location. Over time, should the makefile disappear, they’ll also face problems as well. In another words, being over-dependent makefiles without knowing what’s going on will eventually cause serious problems.

This will also make it difficult to integrate testing tools into source codes that have poor header inclusion management. Unless the code size and complexity is extremely small, quality will always be a problem in any software projects.

So what do I suggest?

Step 1: Select a root source directory

In this case, we’ll select c:\project\src

Step 2: Make it a point to know which header from which module/directory you’re actually using.

I’ve modified the same sample header file:

#include "utility/header1.h"
#include "core/header2.h"
//so and and so forth

*PS, I used ‘/’ instead of ‘\’ so that the code has some minimal cross-platform capabilities.

Conclusion

With this simple habit, it beats the hell out of having to set up complicate makefiles or make setting up of test projects a living nightmare for QA consultants.

One might think - it’s hard to place the relative path if there’re 1 million lines of source codes.

On the surface, that’s true. But who can afford and have the capability to write so many lines of source codes? Surely, it can’t be just a team of five?! For one, I myself took almost 10 years to construct approximately 200,000 lines of source codes.

So what does that mean? It means that there’ll be developers who “owns” these source codes and that the source codes per developer will still be manageable. Not to mention that the individual developers will know exactly what header files they were trying to use.

Lastly, it helps lessen the length of the command line per compilation. Every -I submitted to the compiler means that it must search the given paths should it be unable to find the header file on the first pass. Having a good inclusion management somewhat improves build performance.

Hope that this has been a fruitful sharing session with everyone.

Oh yeah, I left out one thing. Regarding Java Class Files, how does the same problem relate to class files. Well, most of the time it doesn’t. It’s only when code generators are used and that they place the .class files into different project folders. With that, the build master would have to specify the -classpath option for every single class or module in order to build the Java application (J2EE or J2SE alike). That’s why there’re JAR files to help alleviate the pain. Just can’t understand why some people simply refuse to do it the easy way.

Signing off for now,
Jeremy