mirror of
https://github.com/boostorg/website-v2-docs.git
synced 2026-01-19 04:42:17 +00:00
120 lines
4.4 KiB
Plaintext
120 lines
4.4 KiB
Plaintext
////
|
|
Copyright (c) 2024 The C++ Alliance, Inc. (https://cppalliance.org)
|
|
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
|
|
|
Official repository: https://github.com/boostorg/website-v2-docs
|
|
////
|
|
= Headers
|
|
:navtitle: Headers
|
|
:idprefix:
|
|
:idseparator: -
|
|
|
|
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".
|
|
|
|
== Boost Header Standards
|
|
|
|
Here are the standards for boost headers. Many of these are also reasonable guidelines for general use.
|
|
|
|
[disc]
|
|
* 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 <<Sample Header>> uses the Boost convention of all uppercase letters, with the header name prefixed by the namespace name, followed by the relative path, and suffixed with HPP, separated by underscores. Refer also to the <<Example Header Guards>>.
|
|
|
|
* 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 <<Sample Header>> would be included by `#include <boost/furball.hpp>`. Including from the current file directory using `#include "furball.hpp"` syntax is discouraged.
|
|
|
|
* The preferred ordering for class definitions is `public` members, `protected` members, and finally `private` members.
|
|
|
|
* Include the https://www.boost.org/doc/libs/1_83_0/boost/config.hpp[`boost/config.hpp`] if there is a need to deal with compiler or platform configuration issues.
|
|
|
|
== Sample Header
|
|
|
|
[source,cpp]
|
|
----
|
|
|
|
// Boost general library furball.hpp header file ---------------------------//
|
|
|
|
// (C) Copyright <Your Name> 2023. 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 https://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();
|
|
protected:
|
|
double duration();
|
|
private:
|
|
int whatever;
|
|
}; // furball
|
|
|
|
} // namespace
|
|
|
|
#endif // include guard
|
|
----
|
|
|
|
== Example Header Guards
|
|
|
|
Many libraries will include a large number of .hpp header files in a tree structure of folders. Taking boost:beast[] as an example. The header guard code is:
|
|
|
|
[source,cpp]
|
|
----
|
|
#ifndef BOOST_BEAST_HPP
|
|
#define BOOST_BEAST_HPP
|
|
----
|
|
|
|
The subfolder `beast` includes several more headers, including `Core.hpp`, which has the header guard:
|
|
|
|
[source,cpp]
|
|
----
|
|
#ifndef BOOST_BEAST_CORE_HPP
|
|
#define BOOST_BEAST_CORE_HPP
|
|
----
|
|
|
|
In the `beast\core` subfolder there is the `async_base.hpp` header file. Its' guard is:
|
|
|
|
[source,cpp]
|
|
----
|
|
#ifndef BOOST_BEAST_CORE_ASYNC_BASE_HPP
|
|
#define BOOST_BEAST_CORE_ASYNC_BASE_HPP
|
|
----
|
|
|
|
And in the `beast\core\impl` subfolder there is another header named `async_base.hpp`, this time with the guard:
|
|
|
|
[source,cpp]
|
|
----
|
|
#ifndef BOOST_BEAST_CORE_IMPL_ASYNC_BASE_HPP
|
|
#define BOOST_BEAST_CORE_IMPL_ASYNC_BASE_HPP
|
|
----
|
|
|
|
Refer to https://github.com/boostorg/beast/tree/c316c6bd3571991aeac65f0fc35fca9067bc7906/include/boost[beast/include/boost] to view the full hierarchy of folders and headers for this library.
|
|
|
|
|
|
=== Coding Style
|
|
|
|
The alert reader will have noticed that the <<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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|