Changes between Initial Version and Version 1 of Guidelines/Header

Timestamp:

Feb 14, 2010, 12:01:15 PM (13 years ago)

Author:

Daniel James

Comment:

--

Guidelines/Header

@@ +1 @@
+[[PageOutline]]
+
+= Boost Header policy = #intro
+
+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".
+
+Here are the standards for boost headers. Many of these are
+also reasonable guidelines for general use.
+
+
+ * Header filenames should have a .hpp (lowercase) extension.
+ * Unless multiple inclusion is intended, wrap the header in
+   #ifndef guards. Use a naming convention that minimizes the
+   chance of clashes with macro names from other's code. The
+   [#SampleHeader sample header] uses the Boost
+   convention of all uppercase letters, with the header name
+   prefixed by the namespace name, and suffixed with HPP,
+   separated by underscores.
+ * 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 in namespace `boost`.
+ * Make sure that a translation unit consisting of just the
+   contents of the header file will compile successfully.
+ * 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 `#include` directives.
+   Thus the header [#SampleHeader sample header]
+   would be included by `#include <boost/furball.hpp>`
+ * The preferred ordering for class definitions is public
+   members, protected members, and finally private members.
+ * Include the boost/config.hpp
+   [http://www.boost.org/doc/libs/release/libs/config/config.htm configuration header]
+   if there is a need to deal with compiler or
+   platform configuration issues.
+
+== Sample Header == #SampleHeader
+
+{{{
+#!html
+<pre>
+//  Boost general library furball.hpp header file ---------------------------//
+
+  &lt;<i> Copyright and license notice</i>, as indicated in the <a href=
+"http://www.boost.org/users/license.html">license page</a> &gt;
+
+//  See http://www.boost.org/ for latest version.
+
+#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  // include guard
+</pre>
+}}}
+
+== Coding Style == #style
+
+The alert reader will have noticed that the
+[#SampleHeader sample header] 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.