<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <title>Header policy</title> <meta name="GENERATOR" content="Microsoft FrontPage 4.0"> <meta name="ProgId" content="FrontPage.Editor.Document"> <meta name="Microsoft Border" content="none, default"> </head> <body bgcolor="#FFFFFF" text="#000000"> <table border="1" bgcolor="#007F7F" cellpadding="2"> <tr> <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td> <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> </tr> </table> <h1>Header Policy</h1> <p>Header files are the place where a library comes into contact with user code and other libraries. To co-exist peacefully and productively, headers must be "good neighbors".</p> <p>Here are the standards for namespace boost headers. Many of these are also reasonable guidelines for general use. <ul> <li>Headers should have a .hpp (lowercase) filename extension. </li> <li>Wrap the header in #ifndef guards so that multiple inclusion is benign. Use a naming convention that minimizes the chance of clashes with macro names from other's code. The <a href="#Sample header">sample header</a> uses the Boost convention of all uppercase letters, with the header name prefixed by the namespace name, and suffixed with HPP, separated by underscores.</li> <li>Wrap the header contents in a namespace to prevent global namespace pollution. The namespace approach to pollution control is strongly preferred to older approaches such as adding funny prefixes to global names. Libraries which are designed to work well with other Boost libraries should be placed namespace <tt>boost</tt>.</li> <li>Place the header file in a sub-directory to prevent conflict with identically named header files in other libraries. The parent directory is added to the compiler's include search path. Then both your code and user code specifies the sub-directory in <tt>#include</tt> directives. Thus the header <a href="#Sample header">sample header</a> would be included by <tt>#include <boost/furball.hpp></tt></li> <li>The preferred ordering for class definitions is public members, protected members, and finally private members.</li> <li>Include the boost/config.hpp <a href="../libs/config/index.htm">configuration header</a> if there is a need to deal with compiler or platform configuration issues.</li> </ul> <h2><a name="Sample header"></a>Sample Header</h2> <pre><tt>// Boost general library furball.hpp header file ---------------------------// // (C) Copyright Your Name 1998. Permission to copy, use, modify, sell and // distribute this software is granted provided this copyright notice appears // in all copies. This software is provided "as is" without express or implied // warranty, and with no claim as to its suitability for any purpose. // See http://www.boost.org for updates, documentation, and revision history. #ifndef BOOST_FURBALL_HPP #define BOOST_FURBALL_HPP namespace boost { // Furball class declaration -----------------------------------------------// class furball { public: void throw_up(); private: int whatever; }; // furball } // namespace #endif // BOOST_FURBALL_HPP</tt></pre> <h2>Coding Style</h2> <p>The alert reader will have noticed that the <a href="#Sample header">sample header</a> employs a certain coding style for indentation, positioning braces, commenting ending braces, and similar formatting issues. These stylistic issues are viewed as personal preferences and are not part of the Boost Header Policy.</p> <hr> <p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->10 November, 2000<!--webbot bot="Timestamp" endspan i-checksum="39349" --></p> </body> </html>