Re: [boost] Suggested coding guidelines

From: Don Waugaman (dpw_at_[hidden])
Date: 2001-07-03 12:50:01

On Tue, Jul 03, 2001 at 01:21:17PM -0400, David Abrahams wrote:
> 
> That's the idea, but it's just so that if you write two headers on the same
> day they get different #include guards. Others propose putting the path to
> the header in the include guard, which, when combined with mangling:
> 
>     BOOST_PYTHON_DETAIL_EXTENSION_CLASS_DWA07022001_H_
> 
> has no significant advantages over the simpler mangled name:
> 
>     EXTENSION_CLASS_DWA07022001_H_
> 
> (AFAICT).
> 
> > After a quick look at the coding standards, it seems to imply something
> > of this sort (the example preprocessor symbol is RECTANGLE_DWA050499_H_)
> > for the header for the class rectangle.  A Boost-specific convention
> > could be to have the first two underscore-separated names be the name
> > of the file (uppercased, of course) - or perhaps have the file name
> > end with the characters _H_ in the preprocessor symbol, then have the
> > guid after that.
> 
> I think a strong convention is actually harmful, because it will encourage
> users to rely on it.

That's true, but there are two ways of looking at it.

1 - Users rely on it for external include guards, which I agree we should
    discourage.

2 - Library maintainers or those using the library rely on it as a reminder
    of the filename they're working on.  Perhaps it's not vital, but I'd
    hate to do without the mnemonic in one sense or the other.

One possibility would be to bump the guid with every release of Boost.
Writing a script to append guids to the header files shouldn't be too
hard - or, alternately, to change guids that are already there.
Users still couldn't rely on the actual include guard name, but the
convention would still hold for maintainers or onlookers.

> All I care about is:
> 1. #include guards should be sufficiently unique to avoid colliding for all
> practical purposes.

Agreed.

> 2. It should not take me more than about 2 seconds to come up with the
> #include guard for a new header.

Bumping guids with every release should take about two seconds for all the
boost headers :-), with sufficient automation.

> The guideline as written does that. Someone will have to come up with a
> pretty compelling argument to get me to change it. Actually, if the group as
> a whole had a strong preference for something else, and could agree on what
> that was, I would consider changing it, even if the group couldn't justify
> the decision. If y'all want to discuss this and come up with a consensus
> counterproposal, go for it. I will sit out and wait for the outcome.

I'd be happy with the guideline as written, but think that strengthening
it could help.
-- 
    - Don Waugaman (dpw_at_[hidden])    O-             _|_  Will pun
Web Page: http://www.cs.arizona.edu/people/dpw/            |   for food
In the Sonoran Desert, where we say: "It's a dry heat..."  |     <><
Do radioactive cats have 18 half-lives?