Re: Coding guidelines - comments

From: williamkempf_at_[hidden]
Date: 2001-07-05 15:11:20

--- In boost_at_y..., "George A. Heintzelman" <georgeh_at_a...> wrote:
> 
> From: Peter Dimon <pdimov_at_m...>
> > From: "Beman Dawes" <bdawes_at_a...>
> > > Anyhow, we should probably globally change to #include "..."
> > >
> > > That is the correct form for all non-standard library includes, 
and Boost
> > > should be using it.
> > 
> > Using the <...> form has some benefits:
> > 
> 
> > * You know which header is being included, since the current 
directory is
> > not searched (I know that this is implementation-specific, but 
it's often
> > true.)
> 
> I'm not sure which way this ought to go, but I wanted to point one 
a 
> benefit that arises from Peter's point here. Using <...> makes it 
much 
> easier to override/test a fix to a single header, where it might be 
> included by other headers, without having to worry about keeping 
> complete repositories up-to-date, etc. At my workplace we have a 
system 
> in place which takes advantage of this to significantly reduce 
compile 
> times and copies of object files hanging around. It works best when 
(as 
> in our code :( ) there are lots of inter-module dependencies. 
Granted 
> that boost is pretty good in that regard, but lots of user code 
isn't.

I'd like some clarifications here if anyone wants to help me out.  
I've searched the C++ standard for this and have found 16.2 relating 
to this topic.  16.2/2 simply says that #include <...> shall search 
for a header in a sequence of implementation defined places and 
doesn't mention "system headers" at all.  16.2/3 says that 
#include "..." shall search for the file in an implementation defined 
manner, and if not supported or the search fails it will try again as 
if it were #include <...>.  So I can find no mention of "system 
headers".  In fact, there's no help from the standard in 
understanding when to use which style, other than you're gauranteed 
to find the header (if it can be found) using "..." while you may not 
find it using <...>.

The talk of system headers just confuses the issue.  What is a system 
header?  Does this mean a standard header, or simply a header 
provided by the vendor, such as Windows.h on the Windows platform?  
Why should either be given any kind of special treatment over other 
library supplied headers?

I'm used to VC++ where the rules are detailed better.  A #include 
<...> will search for the header in all directories specified on the 
command line or in the INCLUDE environment variable.  A 
#include "..." will search in the current directory, and if that 
fails it will retry as if it were #include <...> as per the 
standard.  This makes usage rules a little easier to define.  If the 
header is part of the current project you use "...", if it's part of 
a seperate library you use <...>.  This gives a *slight* optimization 
in the searching for both file types, and makes it easier for readers 
of the code to find the files as well.  Because of this, that's the 
convention I've always followed.

However, with what I've read in the standard and with other things 
discussed here it seems like the only sensible guideline for portable 
code is to use #include "..." for ALL header files, as dumb as that 
sounds.

What's the historical reasoning behind having both forms?  Are there 
other sections in the standard that define any of this better than 
those I've referenced?  Who's responsible for this mess? ;)

Bill Kempf