RE: [boost] Suggested coding guidelines

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:

PROJECTFOO_TOOLS_BAR_H

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
of
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
GUID.

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
words
library name. This is just as easy to generate and, IMO, reduces even
further
the probability of collision.
I note the this library name doesn't *have to* be anything but as unique as
possible.
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:

BOOST_ITERATOR_HPP,BOOST_GRAPH_ADJACENCY_LIST_HPP

and others David's scheme:

CONFIG_DWA052200_H_

In my proposal, those would become:

BOOST_ITERATOR_04072001_HPP,
BOOST_GRAPH_ADJACENCY_LIST_04072001_HPP
BOOST_PYTHON_CONFIG_052200_H

(*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
unimportant.
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.
fcacciola_at_[hidden]
www.gosierra.com