List:Internals« Previous MessageNext Message »
From:Mats Kindahl Date:October 2 2009 7:08am
Subject:[style] Proposal for include guard naming and usage
View as plain text  
Hi!

I have a proposal for rules regarding the naming and usage of include guard. I
see currently in the code include guards missing, but also used in odd ways that
makes it more difficult to automatically check header files for missing include
guards.


Proposed Rules
--------------

- Include guards shall be of the form ``PACKAGE_HEADER_INCLUDED``,
  that is: the package name followed by the base file name (excluding
  the extension) in all capital letters, numbers, and underscores. The
  package name and the header name is separated by an underscore.

- The header include guard shall be introduced using the form::

    #ifndef PACKAGE_HEADER_INCLUDED
    #define PACKAGE_HEADER_INCLUDED

    ...

    #endif

  Where "PACKAGE" is the name of the package in all capital letters
  and "HEADER" is the name of the header file without extension, e.g.,
  the above include guard is for a file "package/header.h".

  There shall be no code before include guard and no code after the
  matching ``#endif``.

- The header include guard shall be placed first in the file, at the
  first line.


Discussion
----------

In order to prevent include files that are being read multiple times
from repeating definitions, it is customary to add a header include
guard to every header file.  This proposal is to introduce a standard
for naming and placement of these include guards to avoid confusion
and merge problems.

Having a consistent naming scheme for include guards simplifies
automatically checking header files for include guards using automated
tools.

The package name need to be included in the name of the include guard
to allow identical header names in different packages.

The extension is omitted because there are different naming
conventions (.h, .hh, .hpp) and the choice of naming convention for
header files should not affect the include guard name.

The include guard can either be placed before anything in the header
file, or after the first copyright comment that is in each file.  This
proposal suggests that the header include guard be placed first in the
file, at the first line, since this do not require any form of further
parsing of the file to check if the include guard is correctly placed.

-- 
Mats Kindahl
Senior Software Engineer
Database Technology Group
Sun Microsystems
Thread
[style] Proposal for include guard naming and usageMats Kindahl2 Oct
  • Re: [style] Proposal for include guard naming and usageKristian Nielsen2 Oct
    • Re: [style] Proposal for include guard naming and usageMats Kindahl2 Oct
      • Re: [style] Proposal for include guard naming and usageMats Kindahl19 Oct
        • Re: [style] Proposal for include guard naming and usageIngo Strüwing19 Oct
          • Re: [style] Proposal for include guard naming and usageMats Kindahl19 Oct
            • Coding style committee [Re: [style] Proposal for include guard namingand usage]Ingo Strüwing19 Oct
              • Re: Coding style committee [Re: [style] Proposal for include guardnaming and usage]Mats Kindahl20 Oct
                • Re: Coding style committee [Re: [style] Proposal for include guardnaming and usage]Jay Pipes20 Oct
                  • Re: Coding style committee [Re: [style] Proposal for include guardnaming and usage]Ingo Strüwing20 Oct
                    • Re: Coding style committee [Re: [style] Proposal for include guardnaming and usage]Jay Pipes20 Oct