Boost logo

Boost :

From: Fernando Cacciola (fcacciola_at_[hidden])
Date: 2001-07-04 14:48:42

A note about include guards.

I've always used LAST_PART_SUBDIR_FILENAME_EXT, that is:

  For c:\development\projectFoo\tools\bar.h: TOOLS_BAR_H

But although the presence of the last part subdirectory (TOOLS)
does reduce *a lot* the possibility of collision, it still presents
a very small possibility.
One solution could be to use a deeper subdirectory tree:


but that would involve longer names and won't be uniform.

A way to maximize uniqueness is to use a random number.
As we all know, dates and times are good for random numbers, so David's idea
using a date in combination with the filename is a very good idea.
It is easier, IMO, to come up with TOOLS_01012001_H than with a general

Now, just the filename and a date is not enough because the chances that two
different developers create a header with the same name at the same date is
not so small,
so David thought about adding initials to the guard name.
I think his scheme is better than the SUBDIR_FILENAME scheme in that it is
as easy to
construct, but lowers the probability of collisions.

I also agree that external guards are (at least potentially) deprecated, so
a guard
name doesn't have to posses any human-readable meaning. That is, whatever
which is easy
to generate and random enough is OK, regardless of what it *means*.

However, I do see a slight problem that can be easily addressed with a small
change in
the scheme.
It still might happen that the same developer creates more than one file
with the same
filename on the same day (however unlikely), or that two developers have the
same initials
(even more unlikely).
In such a case, the filename-initials-date-ext combination won't work.
But, a library-filename-date-ext combination will do better, as I see it.

I note that I'm only replacing the developer initials with a one-or-two
library name. This is just as easy to generate and, IMO, reduces even
the probability of collision.
I note the this library name doesn't *have to* be anything but as unique as
It can be a part of the directory tree, but not necessarily.

With a random look at some headers from my boost installation, I see that
some follow
the subdir scheme:


and others David's scheme:


In my proposal, those would become:


(*note, I've removed the leading underscore on config, IMO, it doesn't add
anything useful)
(whether it is _HPP or _H, I think it is irrelevant).

Regardless the *meaning* of dates, I still think that it should be
However, if it is, perhaps as a nostalgical mark, something of the form:
_05JUL2001_ would
resolve the date/month ambiguity.

Fernando Cacciola
Sierra s.r.l.

Boost list run by bdawes at, gregod at, cpdaniel at, john at