| 1 | <html> |
|---|
| 2 | |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
|---|
| 5 | <title>Boost Header policy</title> |
|---|
| 6 | <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> |
|---|
| 7 | <meta name="ProgId" content="FrontPage.Editor.Document"> |
|---|
| 8 | <meta name="Microsoft Border" content="none, default"> |
|---|
| 9 | </head> |
|---|
| 10 | |
|---|
| 11 | <body bgcolor="#FFFFFF" text="#000000"> |
|---|
| 12 | |
|---|
| 13 | <table border="1" bgcolor="#007F7F" cellpadding="2"> |
|---|
| 14 | <tr> |
|---|
| 15 | <td bgcolor="#FFFFFF"><img src="../boost.png" alt="boost.png (6897 bytes)" width="277" height="86"></td> |
|---|
| 16 | <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td> |
|---|
| 17 | <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td> |
|---|
| 18 | <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td> |
|---|
| 19 | <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td> |
|---|
| 20 | <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> |
|---|
| 21 | </tr> |
|---|
| 22 | </table> |
|---|
| 23 | <h1>Boost Header Policy</h1> |
|---|
| 24 | <p>Header files are the place where a library comes into contact with user code |
|---|
| 25 | and other libraries. To co-exist peacefully and productively, headers must |
|---|
| 26 | be "good neighbors".</p> |
|---|
| 27 | <p>Here are the standards for namespace boost headers. Many of |
|---|
| 28 | these are also reasonable guidelines for general use. |
|---|
| 29 | <ul> |
|---|
| 30 | <li>Headers should have a .hpp (lowercase) filename extension. </li> |
|---|
| 31 | <li>Wrap the header in #ifndef guards so that multiple inclusion is |
|---|
| 32 | benign. Use a naming convention that minimizes the chance of clashes |
|---|
| 33 | with macro names from other's code. The <a href="#Sample header">sample |
|---|
| 34 | header</a> uses the Boost convention of all uppercase letters, with the |
|---|
| 35 | header name prefixed by the namespace name, and suffixed with HPP, separated |
|---|
| 36 | by underscores.</li> |
|---|
| 37 | <li>Wrap the header contents in a namespace to prevent global namespace |
|---|
| 38 | pollution. The namespace approach to pollution control is strongly preferred |
|---|
| 39 | to older approaches such as adding funny prefixes to global names. |
|---|
| 40 | Libraries which are designed to work well with other Boost libraries should |
|---|
| 41 | be placed namespace <tt>boost</tt>.</li> |
|---|
| 42 | |
|---|
| 43 | <li>Make sure that a translation unit consisting of just the |
|---|
| 44 | contents of the header file will compile successfully. |
|---|
| 45 | |
|---|
| 46 | <li>Place the header file in a sub-directory to prevent conflict with |
|---|
| 47 | identically named header files in other libraries. The parent |
|---|
| 48 | directory is added to the compiler's include search path. Then both |
|---|
| 49 | your code and user code specifies the sub-directory in <tt>#include</tt> |
|---|
| 50 | directives. Thus the header <a href="#Sample header">sample header</a> |
|---|
| 51 | would be included by <tt>#include <boost/furball.hpp></tt></li> |
|---|
| 52 | <li>The preferred ordering for class definitions is public members, protected |
|---|
| 53 | members, and finally private members.</li> |
|---|
| 54 | <li>Include the boost/config.hpp <a href="../libs/config/config.htm">configuration |
|---|
| 55 | header</a> if there is a need to deal with compiler or platform |
|---|
| 56 | configuration issues.</li> |
|---|
| 57 | </ul> |
|---|
| 58 | <h2><a name="Sample header"></a>Sample Header</h2> |
|---|
| 59 | <pre><tt>// Boost general library furball.hpp header file ---------------------------// |
|---|
| 60 | |
|---|
| 61 | // (C) Copyright Your Name 1998. Permission to copy, use, modify, sell and |
|---|
| 62 | // distribute this software is granted provided this copyright notice appears |
|---|
| 63 | // in all copies. This software is provided "as is" without express or implied |
|---|
| 64 | // warranty, and with no claim as to its suitability for any purpose. |
|---|
| 65 | |
|---|
| 66 | // See http://www.boost.org for updates, documentation, and revision history. |
|---|
| 67 | |
|---|
| 68 | #ifndef BOOST_FURBALL_HPP |
|---|
| 69 | #define BOOST_FURBALL_HPP |
|---|
| 70 | |
|---|
| 71 | namespace boost { |
|---|
| 72 | |
|---|
| 73 | // Furball class declaration -----------------------------------------------// |
|---|
| 74 | |
|---|
| 75 | class furball |
|---|
| 76 | { |
|---|
| 77 | public: |
|---|
| 78 | void throw_up(); |
|---|
| 79 | private: |
|---|
| 80 | int whatever; |
|---|
| 81 | }; // furball |
|---|
| 82 | |
|---|
| 83 | } // namespace |
|---|
| 84 | |
|---|
| 85 | #endif // BOOST_FURBALL_HPP</tt></pre> |
|---|
| 86 | <h2>Coding Style</h2> |
|---|
| 87 | <p>The alert reader will have noticed that the <a href="#Sample header">sample |
|---|
| 88 | header</a> employs a certain coding style for indentation, positioning braces, |
|---|
| 89 | commenting ending braces, and similar formatting issues. These stylistic |
|---|
| 90 | issues are viewed as personal preferences and are not part of the Boost Header |
|---|
| 91 | Policy.</p> |
|---|
| 92 | <hr> |
|---|
| 93 | <p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->02 October, 2003<!--webbot bot="Timestamp" endspan i-checksum="38549" --></p> |
|---|
| 94 | |
|---|
| 95 | <p>© Copyright Beman Dawes 1998</p> |
|---|
| 96 | <p> Use, modification, and distribution are subject to the Boost Software |
|---|
| 97 | License, Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt"> |
|---|
| 98 | LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt"> |
|---|
| 99 | www.boost.org/LICENSE_1_0.txt</a>)</p> |
|---|
| 100 | |
|---|
| 101 | </body> |
|---|
| 102 | |
|---|
| 103 | </html> |
|---|
