+ Many organization already use programs implemented with Boost, like Adobe
+ Acrobat
+ Reader 7.0.
+
+
+ "...one of the most highly regarded and expertly designed C++ library
+ projects in the world."
+
+
+
+ "The obvious solution for most programmers is to use a library that
+ provides an elegant and efficient platform independent to needed services.
+ Examples are BOOST..."
+
+
+ The Boost libraries tend to be new, fresh, and creative designs. They are
+ not copies, clones, or derivations of proprietary libraries. Boost has a
+ firm policy to respect the IP rights of others. The development of Boost
+ libraries is publicly documented via the mailing lists and version control
+ repository. The source code has been inspected by many, many knowledgeable
+ programmers. Each Boost file has a copyright notice and license
+ information. IP issues have been reviewed by the legal teams from some of
+ the corporations which use Boost, and in some cases these lawyers have been
+ kind enough to give Boost feedback on IP issues. There are no guarantees,
+ but those factors all tend to reduce IP risk.
+
+
+
+ Businesses and other organizations often prefer to have code developed,
+ maintained, and improved in the open source community when it does not
+ contain technology specific to their application domain, because it allows
+ them to focus more development resources on their core business.
+
+
+ Individuals contribute for the technical challenge, to hone their technical
+ skills, for the sense of community, as part of their graduate school
+ programs, as a way around geographic isolation, to enhance their employment
+ opportunities, and as advertisements for their consulting services. There
+ are probably as many reasons as there are individuals. Some of the
+ apparently individual contributions come from employees of support
+ companies with contracts from businesses or other organizations who have an
+ interest in seeing that a library is well-maintained.
+
+
+ Boost doesn't really have any expenses! All the infrastructure is
+ contributed by supporters, such as the Open Systems Lab at Indiana University,
+
+ SourceForge, Boost Consulting, MetaCommunications, and the individuals,
+ companies, and other organizations who run the regression tests. Borland,
+ HP, Intel, and Microsoft have contributed compilers. And hundreds, or even
+ thousands, of programmers contribute their time. That's what makes Boost
+ possible.
+
+
-
-  |
- Home |
- Libraries |
- People |
- FAQ |
- More |
-
+
+
+ Boost Library Requirements and Guidelines
+
+
+
+
+
+
+
+
+
+
+
+ Boost Library Requirements and Guidelines
+
+
+ Introduction
+ Requirements
+ License requirements
+ Portability requirements
+
+ Ownership
+ Guidelines
+ Design and
+ programming
+ Directory structure and
+ filenames
+ Naming
+ consistency
+
+ Documentation
+ Rationale
+ Exception-specification rationale
+ Naming conventions rationale
+ Source code fonts
+ rationale
+
+ Tabs rationale
+ ECMAScript/JavaScript
+ rationale
+ Rationale
+ rationale
+ Acknowledgements
+ rationale
+
+
+
+
+ This page describes requirements and guidelines for the content of a
+ library submitted to Boost.
+
+
+ See the Boost Library Submission
+ Process page for a description of the process involved.
+
+
+
+
+ To avoid the frustration and wasted time of a proposed library being
+ rejected, it must meets these requirements:
+
+
+ - The license must meet the license requirements
+
+ below. Restricted licenses like the GPL and LGPL are not acceptable.
+
+ - The copyright ownership must be clear.
+
+ - The library must be generally useful and not restricted to a narrow
+ problem domain.
+
+ - The library must meet the portability
+ requirements below.
+
+
+ - The library must come reasonably close to meeting the Guidelines below.
+
+
+ - The author must be willing to participate in discussions on the mailing
+ list, and to refine the library accordingly.
+
+
+
+
+ There's no requirement that an author read the mailing list for a time
+ before making a submission. It has been noted, however, that submissions
+ which begin "I just started to read this mailing list ..." seem to fail,
+ often embarrassingly.
+
+
+ License requirements
+
+
+ The preferred way to meet the license requirements is to use the Boost Software License. See license information. If for any reason you do not
+ intend to use the Boost Software License, please discuss the issues on the
+ Boost developers mailing list first.
+
+
+
+ The license requirements:
+
+
+ - Must be simple to read and understand.
+
+ - Must grant permission without fee to copy, use and modify the software
+ for any use (commercial and non-commercial).
+
+ - Must require that the license appear on all copies of the software
+ source code.
+
+ - Must not require that the license appear with executables or other
+ binary uses of the library.
+
+
+ - Must not require that the source code be available for execution or
+ other binary uses of the library.
+
+ - May restrict the use of the name and description of the library to the
+ standard version found on the Boost web site.
+
+
+
+
+
+ -
+
+ A library's interface must portable and not restricted to a particular
+ compiler or operating system.
+
+
+ -
+
+ A library's implementation must if possible be portable and not
+ restricted to a particular compiler or operating system. If a
+ portable implementation is not possible, non-portable constructions are
+ acceptable if reasonably easy to port to other environments, and
+ implementations are provided for at least two popular operating systems
+ (such as UNIX and Windows).
+
+
+
+ -
+
+ There is no requirement that a library run on C++ compilers which do
+ not conform to the ISO standard.
+
+
+ -
+
+
+ There is no requirement that a library run on any particular C++
+ compiler. Boost contributors often try to ensure their libraries
+ work with popular compilers. The boost/config.hpp configuration header is the preferred
+ mechanism for working around compiler deficiencies.
+
+
+
+
+ Since there is no absolute way to prove portability, many boost submissions
+ demonstrate practical portability by compiling and executing correctly with
+ two different C++ compilers, often under different operating systems.
+
+ Otherwise reviewers may disbelieve that porting is in fact practical.
+
+
+
+ Are you sure you own the library you are thinking of
+ submitting? "How to Copyright Software" by MJ Salone, Nolo
+ Press, 1990 says:
+
+
+
+
+ Doing work on your own time that is very similar to programming you do
+ for your employer on company time can raise nasty legal problems.
+ In this situation, it's best to get a written release from your employer
+ in advance.
+
+
+
+ Place a copyright notice in all the important files you submit. Boost won't
+ accept libraries without clear copyright information.
+
+
+
+
+ Please use these guidelines as a checklist for preparing the content a
+ library submission. Not every guideline applies to every library, but
+ a reasonable effort to comply is expected.
+
+
+
+ - Aim first for clarity and correctness; optimization should be only a
+ secondary concern in most Boost libraries.
+
+
+
+ - Aim for ISO Standard C++. Than means making effective use of the
+ standard features of the language, and avoiding non-standard compiler
+ extensions. It also means using the C++ Standard Library where applicable.
+
+
+
+
+ - Follow quality programming practices. See, for example, "Effective C++"
+ 2nd Edition, and "More Effective C++", both by Scott Meyers, published by
+ Addison Wesley.
+
+
+
+
+ - Use the C++ Standard Library or other Boost libraries, but only when
+ the benefits outweigh the costs. Do not use libraries other than the
+ C++ Standard Library or Boost. See Library
+ reuse.
+
+
+
+
+
+ - Use the naming conventions of the C++ Standard Library (See Naming conventions rationale):
+
+
+
+ - Names (except as noted below) should be all lowercase, with words
+ separated by underscores.
+
+ - Acronyms should be treated as ordinary names (e.g.
+
xml_parser instead of XML_parser).
+
+ - Template parameter names begin with an uppercase letter.
+
+
+ - Macro (gasp!) names all uppercase and begin with BOOST_.
+
+
+
+
+
+ - Choose meaningful names - explicit is better than implicit, and
+ readability counts. There is a strong preference for clear and descriptive
+ names, even if lengthy.
+
+
+
+
+ - Use exceptions to report errors where appropriate, and write code that
+ is safe in the face of exceptions.
+
+
+
+
+
+ - Provide sample programs or confidence tests so potential users can see
+ how to use your library.
+
+
+
+
+ - Although some boost members use proportional fonts, tabs, and
+ unrestricted line lengths in their own code, boost's widely distributed
+ source code should follow more conservative guidelines:
+
+
+
+
+
+ - End all documentation files (HTML or otherwise) with a copyright
+ message and a licensing message. See license
+ information page for the preferred form.
+
+
+
+ - Begin all source files (including programs, headers, scripts, etc.)
+ with:
+
+
+
+ - A comment line describing the contents of the file.
+
+
+ - Comments describing copyright and licensing: again, the preferred
+ form is indicated in the license
+ information page
+
+
+ Note that developers should not provide a copy of
+ LICENSE_1_0.txt with their libraries: Boost
+ distributions already include a copy in the Boost root directory.
+
+
+ - A comment line referencing your library on the Boost web site. For
+ example:
+
+
+ // See http://www.boost.org/libs/foo/ for library home
+ page.
+
+ where foo is the directory name (see below) for the
+ library. As well as aiding users who come across a Boost file
+ detached from its documentation, some of Boost's automatic tools
+ depend on this comment to identify which library header files belong
+ to.
+
+
+
+
+
+
+ - Make sure your code compiles in the presence of the
min()
+ and max() macros. Some platform headers define
+ min() and max() macros which cause some common
+ C++ constructs to fail to compile. Some simple tricks can protect your code
+ from inappropriate macro substitution:
+
+
+
+ - If you want to call
std::min() or
+ std::max():
+
+
+ - If you do not require argument-dependent look-up, use
+
(std::min)(a,b).
+
+
+ -
+
+
+ - If you do require argument-dependent look-up, you should:
+
+ -
+
+
+ -
+
+
#include <boost/config.hpp>
+
+ - Use
BOOST_USING_STD_MIN(); to bring
+ std::min() into the current scope.
+
+ - Use
min BOOST_PREVENT_MACRO_SUBSTITUTION
+ (a,b); to make an argument-dependent call to
+ min(a,b).
+
+
+
+
+
+
+ -
+
+
+ - If you want to call
+
std::numeric_limits<int>::max(), use
+ (std::numeric_limits<int>::max)() instead.
+
+
+ -
+
+
+ - If you want to call a
min() or max()
+ member function, instead to doing obj.min(), use
+ (obj.min)().
+
+
+ -
+
+
+ - If you want to declare or define a function or a member function
+ named
min or max, then you must use the
+ BOOST_PREVENT_MACRO_SUBSTITUTION macro. Instead of writing
+ int min() { return 0; } you should write int min
+ BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }
+
+ This is true regardless if the function is a free (namespace scope)
+ function, a member function or a static member function, and it
+ applies for the function declaration as well as for the function
+ definition.
+
+
+
+
+
+
+
+ - File and directory names must contain only lowercase ASCII
+ letters , numbers, underscores, and a period. Leading character must
+ be alphabetic. Maximum length 31. Only a single period is permitted.
+ These requirements ensure file and directory names are relatively portable.
+
+ - Files intended to be processed by a C++ compiler as part of a
+ translation unit should have a three-letter filename extension ending in
+ "pp". Other files should not use extensions ending in "pp". This
+ convention makes it easy to identify all of the C++ source in Boost.
+
+
+ - All libraries have at their highest level a primary directory named for
+ the particular library. See Naming
+ consistency. The primary directory may have sub-directories.
+
+ - For very simple libraries implemented entirely within the library
+ header, all files go in the primary directory (except headers, which go in
+ the boost header directory).
+
+
+
+
+ Boost standard sub-directory names
+
+
+
+
+ |
+ Sub-directory
+ |
+
+ Contents
+
+ |
+
+ Required
+ |
+
+
+
+ build
+
+ |
+
+ Library build files such as a Jamfile.
+ |
+
+ If any build files.
+ |
+
+
+
+
+ doc
+ |
+
+ Documentation (HTML) files.
+ |
+
+ If several doc files.
+ |
+
+
+
+
+ example
+ |
+
+ Sample program files.
+ |
+
+ If several sample files.
+ |
+
+
+
+
+ src
+ |
+
+ Source files which must be compiled to build the library.
+ |
+
+
+ If any source files.
+ |
+
+
+
+ test
+ |
+
+
+ Regression or other test programs or scripts.
+ |
+
+ If several test files.
+ |
+
- Boost Library Requirements and Guidelines
- Introduction
- Requirements
- License requirements
- Portability requirements
- Ownership
- Guidelines
- Design and programming
- Directory structure and
- filenames
- Naming consistency
- Documentation
- Rationale
- Exception-specification
- rationale
- Naming conventions rationale
- Source code fonts rationale
- Tabs rationale
- ECMAScript/JavaScript rationale
- Rationale rationale
- Acknowledgements rationale
-
- This page describes requirements and guidelines for the content of
- a library submitted to Boost.
- See the Boost Library Submission
- Process page for a description of the process involved.
-
- To avoid the frustration and wasted time of a proposed library being rejected,
- it must meets these requirements:
-
- -
- The license must meet the license requirements
- below. Restricted licenses like the GPL and LGPL are not acceptable.
-
-
- The copyright ownership
- must be clear.
-
-
- The library must be generally useful and not restricted to a narrow problem
- domain.
-
-
- The library must meet the portability requirements
- below.
-
-
- The library must come reasonably close to meeting the Guidelines
- below.
-
-
-
- The author must be willing to participate in discussions on the mailing list,
- and to refine the library accordingly.
-
- There's no requirement that an author read the mailing list for a time before
- making a submission. It has been noted, however, that submissions which begin
- "I just started to read this mailing list ..." seem to fail, often
- embarrassingly.
-
- The preferred way to meet the license requirements is to use the
- Boost Software License. See license information.
- If for any reason you do not intend to use the Boost Software License, please
- discuss the issues on the Boost developers
- mailing list first.
- The license requirements:
-
- -
- Must be simple to read and understand.
-
-
- Must grant permission without fee to copy, use and modify the software for any
- use (commercial and non-commercial).
-
-
- Must require that the license appear on all copies of the software source code.
-
-
- Must not require that the license appear with executables or other binary uses
- of the library.
-
-
- Must not require that the source code be available for execution or other
- binary uses of the library.
-
-
- May restrict the use of the name and description of the library to the standard
- version found on the Boost web site.
-
-
-
- -
-
A library's interface must portable and not restricted to a
- particular compiler or operating system.
- -
-
A library's implementation must if possible be portable and not
- restricted to a particular compiler or operating system. If a portable
- implementation is not possible, non-portable constructions are acceptable if
- reasonably easy to port to other environments, and implementations are provided
- for at least two popular operating systems (such as UNIX and Windows).
- -
-
There is no requirement that a library run on C++ compilers which
- do not conform to the ISO standard.
- -
-
There is no requirement that a library run on any particular C++
- compiler. Boost contributors often try to ensure their libraries work
- with popular compilers. The boost/config.hpp
- configuration header is the preferred mechanism for working around
- compiler deficiencies.
-
-
- Since there is no absolute way to prove portability, many boost
- submissions demonstrate practical portability by compiling and executing
- correctly with two different C++ compilers, often under different operating
- systems. Otherwise reviewers may disbelieve that porting is in fact
- practical.
-
- Are you sure you own the library you are thinking of
- submitting? "How to Copyright Software" by MJ Salone, Nolo Press,
- 1990 says:
-
- Doing work on your own time that is very similar to programming
- you do for your employer on company time can raise nasty legal problems.
- In this situation, it's best to get a written release from your employer in
- advance.
-
- Place a copyright notice in all the important files you submit.
- Boost won't accept libraries without clear copyright information.
-
- Please use these guidelines as a checklist for preparing the
- content a library submission. Not every guideline applies to every
- library, but a reasonable effort to comply is expected.
-
-
- -
- Aim first for clarity and correctness; optimization should be only a secondary
- concern in most Boost libraries.
-
-
- -
- Aim for ISO Standard C++. Than means making effective use of the standard
- features of the language, and avoiding non-standard compiler extensions. It
- also means using the C++ Standard Library where applicable.
-
-
-
- -
- Follow quality programming practices. See, for example, "Effective C++" 2nd
- Edition, and "More Effective C++", both by Scott Meyers, published by Addison
- Wesley.
-
-
- -
- Use the C++ Standard Library or other Boost libraries, but only when the
- benefits outweigh the costs. Do not use libraries other than the C++
- Standard Library or Boost. See Library reuse.
-
-
-
-
- -
- Use the naming conventions of the C++ Standard Library (See Naming
- conventions rationale):
-
-
- -
- Names (except as noted below) should be all lowercase, with words separated by
- underscores.
-
-
- Acronyms should be treated as ordinary names (e.g.
xml_parser instead
- of XML_parser).
- -
- Template parameter names begin with an uppercase letter.
-
-
- Macro (gasp!) names all uppercase and begin with BOOST_.
-
-
-
-
- -
- Choose meaningful names - explicit is better than implicit, and readability
- counts. There is a strong preference for clear and descriptive names, even if
- lengthy.
-
-
- -
- Use exceptions to report errors where appropriate, and write code that is safe
- in the face of exceptions.
-
-
-
- -
- Provide sample programs or confidence tests so potential users can see how to
- use your library.
-
-
-
- -
- Although some boost members use proportional fonts, tabs, and unrestricted line
- lengths in their own code, boost's widely distributed source code should follow
- more conservative guidelines:
-
-
-
-
- -
- End all documentation files (HTML or otherwise) with a copyright message and a
- licensing message. See the end of this file for an
- example of the preferred form.
-
-
- -
- Begin all source files (including programs, headers, scripts, etc.) with:
-
-
- -
- A comment line describing the contents of the file.
-
- -
- Comments describing copyright and licensing. The preferred form is:
-
- // Copyright Jane Programmer 2002. Use, modification, and distribution
- are
- // subject to 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)
-
-
- Please leave an empty line before and after the copyright and license comments.
- It is fine if the copyright and license messages are on different lines, but
- there should be no other intervening text. Do not include "All rights reserved"
- in the copyright message.
-
- See license information page for more
- information about the Boost Software License.
-
- Note that developers should not include a copy of LICENSE_1_0.txt in
- their libraries; Boost distributions already include a copy in the Boost root
- directory.
-
- -
- A comment line referencing your library on the Boost web site. For example:
-
- // See http://www.boost.org/libs/foo for library home page.
-
- where foo is the directory name (see below) for your library. As
- well as aiding users who come across a Boost file detached from its
- documentation, some of Boost's automatic tools depend on this comment to
- identify which library header files belong to.
-
-
-
-
- -
- Make sure your code compiles in the presence of the
min() and max()
- macros. Some platform headers define min() and max() macros which
- cause some common C++ constructs to fail to compile. Some simple tricks can protect your code
- from inappropriate macro substitution:
-
- -
- If you want to call
std::min() or std::max():
-
- -
- If you do not require argument-dependent look-up, use
(std::min)(a,b).
-
- -
- If you do require argument-dependent look-up, you should:
-
- #include <boost/config.hpp>- Use
BOOST_USING_STD_MIN(); to bring std::min() into
- the current scope.
- - Use
min BOOST_PREVENT_MACRO_SUBSTITUTION (a,b); to make an
- argument-dependent call to min(a,b).
-
-
-
-
- -
- If you want to call
std::numeric_limits<int>::max(), use
- (std::numeric_limits<int>::max)() instead.
-
- -
- If you want to call a
min() or max() member function,
- instead to doing obj.min(), use (obj.min)().
-
- -
- If you want to declare or define a function or a member function named
min
- or max, then you must use the BOOST_PREVENT_MACRO_SUBSTITUTION
- macro. Instead of writing int min() { return 0; } you should write
- int min BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; } This is true
- regardless if the function is a free (namespace scope) function, a member function or a
- static member function, and it applies for the function declaration as well as the
- function definition.
-
-
-
-
-
-
- -
- File and directory names must contain only lowercase ASCII letters , numbers,
- underscores, and a period. Leading character must be alphabetic. Maximum
- length 31. Only a single period is permitted. These requirements ensure
- file and directory names are relatively portable.
-
-
- Files intended to be processed by a C++ compiler as part
- of a translation unit should have a three-letter
- extension ending in "pp". Other files should
- not use extensions ending in "pp". This
- convention makes it easy to identify all of the C++ source
- in Boost.
- -
- All libraries have at their highest level a primary directory named for the
- particular library. See Naming consistency.
- The primary directory may have sub-directories.
-
-
- For very simple libraries implemented entirely within the library header, all
- files go in the primary directory (except headers, which go in the boost header
- directory).
-
-
- Boost standard sub-directory names
-
-
- | Sub-directory |
- Contents |
- Required |
-
-
- build |
- Library build files such as a Jamfile. |
- If any build files. |
-
-
- doc |
- Documentation (HTML) files. |
- If several doc files. |
-
-
- example |
- Sample program files. |
- If several sample files. |
-
-
- src |
- Source files which must be compiled to build the library. |
- If any source files. |
-
-
- test |
- Regression or other test programs or scripts. |
- If several test files. |
-
-
-
-
- The primary directory should always contain a file named index.html (or
- index.htm). Authors have requested this so that they can publish URL's in the
- form http://www.boost.org/libs/lib-name with the assurance a
- documentation reorganization won't invalidate the URL. Boost's internal tools
- are also simplified by knowing that a library's documentation is always
- reachable via the simplified URL.
- If the documentation is in a doc sub-directory, the primary directory
- index.html file should just do an automatic redirection to the doc
- subdirectory:
-
- <html>
+
+
+
+ The primary directory should always contain a file named index.html (or
+ index.htm). Authors have requested this so that they can publish URL's in
+ the form http://www.boost.org/libs/lib-name with the assurance a
+ documentation reorganization won't invalidate the URL. Boost's internal
+ tools are also simplified by knowing that a library's documentation is
+ always reachable via the simplified URL.
+
+
+ If the documentation is in a doc sub-directory, the primary directory
+ index.html file should just do an automatic redirection to the doc
+ subdirectory:
+
+
+
+
+<html>
<head>
<meta http-equiv="refresh" content="0; URL=doc/index.html">
</head>
<body>
Automatic redirection failed, please go to
<a href="doc/index.html">doc/index.html</a>
+
</body>
-</html>
-
-
- As library developers and users have gained experience with Boost, the
- following consistent naming approach has come to be viewed as very helpful,
- particularly for larger libraries that need their own header subdirectories
- and namespaces.
- Here is how it works. The library is given a name that describes the contents
- of the library. Cryptic abbreviations are strongly discouraged. Following the
- practice of the C++ Standard Library, names are usually singular rather than
- plural. For example, a library dealing with file systems might chose the
- name "filesystem", but not "filesystems", "fs" or "nicecode".
-
- -
- The library's primary directory (in parent boost-root/libs) is given
- that same name. For example, boost-root/libs/filesystem.
-
- -
- The library's primary header directory (in parent boost-root/boost) is
- given that same name. For example, boost-root/boost/filesystem.
-
- -
- The library's primary namespace (in parent ::boost) is given that same
- name, except when there's a component with that name (e.g., boost::tuple), in which case the namespace name is pluralized. For example, ::boost::filesystem.
-
-
- When documenting Boost libraries, follow these conventions (see also the following section of this document):
-
- - The library name is set in roman type.
- - The library name is capitalized.
- - A period between "Boost" and the library name (e.g., Boost.Bind) is used if and only if the library name is not followed by the word "library".
- - The word "library" is not part of the library name and is therefore lowercased.
-
- Here are a few examples of how to apply these conventions:
-
- - Boost.Bind was written by Peter Dimov.
- - The Boost Bind library was written by Peter Dimov.
- - I regularly use Bind, a Boost library written by Peter Dimov.
-
-
-
- Even the simplest library needs some documentation; the amount should be
- proportional to the need. The documentation should assume the readers
- have a basic knowledge of C++, but are not necessarily experts.
- The format for documentation should be HTML, and should not require an advanced
- browser or server-side extensions. Style sheets are acceptable.
- ECMAScript/JavaScript is not acceptable. The documentation entry point should
- always be a file named index.html or index.htm; see Redirection.
- There is no single right way to do documentation. HTML documentation is often
- organized quite differently from traditional printed documents. Task-oriented
- styles differ from reference oriented styles. In the end, it comes down to the
- question: Is the documentation sufficient for the mythical "average" C++
- programmer to use the library successfully?
- Appropriate topics for documentation often include:
-
- -
- General introduction to the library.
-
-
- Description of each class.
-
-
- Relationship between classes.
-
-
- For each function, as applicable, description, requirements (preconditions),
- effects, post-conditions, returns, and throws.
-
-
- Discussion of error detection and recovery strategy.
-
-
- How to use including description of typical uses.
-
-
- How to compile and link.
-
-
- How to test.
-
-
- Version or revision history.
-
-
- Rationale for design decisions. See Rationale rationale.
-
-
- Acknowledgements. See Acknowledgments rationale.
-
- If you need more help with how to write documentation you can check out the
- article on Writing Documentation for Boost.
-
- Rationale for some of the requirements and guidelines follows.
-
-
- Exception specifications [ISO 15.4] are sometimes coded to indicate what
- exceptions may be thrown, or because the programmer hopes they will improved
- performance. But consider the following member from a smart pointer:
- T& operator*() const throw() { return *ptr; }
- This function calls no other functions; it only manipulates fundamental data
- types like pointers Therefore, no runtime behavior of the
- exception-specification can ever be invoked. The function is completely
- exposed to the compiler; indeed it is declared inline Therefore, a smart
- compiler can easily deduce that the functions are incapable of throwing
- exceptions, and make the same optimizations it would have made based on the
- empty exception-specification. A "dumb" compiler, however, may make all kinds
- of pessimizations.
- For example, some compilers turn off inlining if there is an
- exception-specification. Some compilers add try/catch blocks. Such
- pessimizations can be a performance disaster which makes the code unusable in
- practical applications.
- Although initially appealing, an exception-specification tends to have
- consequences that require very careful thought to understand. The
- biggest problem with exception-specifications is that programmers use them as
- though they have the effect the programmer would like, instead of the effect
- they actually have.
- A non-inline function is the one place a "throws nothing"
- exception-specification may have some benefit with some compilers.
-
- Naming conventions rationale
- The C++ standard committee's Library Working Group discussed this issue in
- detail, and over a long period of time. The discussion was repeated again in
- early boost postings. A short summary:
-
- -
- Naming conventions are contentious, and although several are widely used, no
- one style predominates.
-
-
- Given the intent to propose portions of boost for the next revision of the C++
- standard library, boost decided to follow the standard library's conventions.
-
-
- Once a library settles on a particular convention, a vast majority of
- stakeholders want that style to be consistently used.
-
-
-
-
- Dave Abrahams comments: An important purpose (I daresay the primary purpose) of
- source code is communication: the documentation of intent. This is a doubly
- important goal for boost, I think. Using a fixed-width font allows us to
- communicate with more people, in more ways (diagrams are possible) right there
- in the source. Code written for fixed-width fonts using spaces will read
- reasonably well when viewed with a variable-width font, and as far as I can
- tell every editor supporting variable-width fonts also supports fixed width. I
- don't think the converse is true.
-
- Tabs rationale
- Tabs are banned because of the practical problems caused by tabs in
- multi-developer projects like Boost, rather than any dislike in principle. See
- mailing list archives. Problems include maintenance of a single source
- file by programmers using tabs and programmers using spaces, and the difficulty
- of enforcing a consistent tab policy other than just "no tabs". Discussions
- concluded that Boost files should either all use tabs, or all use spaces, and
- thus the decision to stick with spaces.
-
- ECMAScript/JavaScript rationale
- Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript
- documentation. Controversy followed (see mailing
- list archives), and the developers were asked to remove the
- ECMAScript/JavaScript. Reasons given for banning included:
-
- -
- Incompatible with some older browsers and some text based browsers.
-
-
- Makes printing docs pages difficult.
-
-
- Often results in really bad user interface design.
-
-
- "It's just annoying in general."
-
-
- Would require Boost to test web pages for ECMAScript/JavaScript compliance.
-
-
- Makes docs maintenance by other than the original developer more difficult.
-
-
-
- Rationale is defined as "The fundamental reasons for something; basis" by the
- American Heritage Dictionary.
- Beman Dawes comments: Failure to supply contemporaneous rationale for
- design decisions is a major defect in many software projects. Lack of accurate
- rationale causes issues to be revisited endlessly, causes maintenance bugs when
- a maintainer changes something without realizing it was done a certain way for
- some purpose, and shortens the useful lifetime of software.
- Rationale is fairly easy to provide at the time decisions are made, but very
- hard to accurately recover even a short time later.
-
-
- As a library matures, it almost always accumulates improvements suggested to
- the authors by other boost members. It is a part of the culture of
- boost.org to acknowledge such contributions, identifying the person making the
- suggestion. Major contributions are usually acknowledged in the
- documentation, while minor fixes are often mentioned in comments within the
- code itself.
-
- Revised
-
- 04 November, 2003
-
- © Copyright Beman Dawes 2003.
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or
- copy at www.boost.org/LICENSE_1_0.txt)
+</html>
+
+
+
+
+ As library developers and users have gained experience with Boost, the
+ following consistent naming approach has come to be viewed as very helpful,
+ particularly for larger libraries that need their own header subdirectories
+ and namespaces.
-
+
+
+ Here is how it works. The library is given a name that describes the
+ contents of the library. Cryptic abbreviations are strongly discouraged.
+ Following the practice of the C++ Standard Library, names are usually
+ singular rather than plural. For example, a library dealing with file
+ systems might chose the name "filesystem", but not "filesystems", "fs" or
+ "nicecode".
+
+
+ - The library's primary directory (in parent boost-root/libs) is
+ given that same name. For example,
+ boost-root/libs/filesystem.
+
+
+
+ - The library's primary header directory (in parent
+ boost-root/boost) is given that same name. For example,
+ boost-root/boost/filesystem.
+
+
+ - The library's primary namespace (in parent ::boost) is given
+ that same name, except when there's a component with that name (e.g.,
+ boost::tuple), in which case the namespace name is pluralized. For
+ example, ::boost::filesystem.
+
+
+
+
+ When documenting Boost libraries, follow these conventions (see also the
+ following section of this document):
+
+
+ - The library name is set in roman type.
+
+ - The library name is capitalized.
+
+ - A period between "Boost" and the library name (e.g., Boost.Bind) is
+ used if and only if the library name is not followed by the word "library".
+
+
+ - The word "library" is not part of the library name and is therefore
+ lowercased.
+
+
+
+ Here are a few examples of how to apply these conventions:
+
+
+ - Boost.Bind was written by Peter Dimov.
+
+ - The Boost Bind library was written by Peter Dimov.
+
+
+ - I regularly use Bind, a Boost library written by Peter Dimov.
+
+
+
+
+ Even the simplest library needs some documentation; the amount should be
+ proportional to the need. The documentation should assume the readers
+ have a basic knowledge of C++, but are not necessarily experts.
+
+
+
+ The format for documentation should be HTML, and should not require an
+ advanced browser or server-side extensions. Style sheets are acceptable.
+ ECMAScript/JavaScript is not acceptable. The documentation entry point
+ should always be a file named index.html or index.htm; see Redirection.
+
+
+ There is no single right way to do documentation. HTML documentation is
+ often organized quite differently from traditional printed documents.
+ Task-oriented styles differ from reference oriented styles. In the end, it
+ comes down to the question: Is the documentation sufficient for the
+ mythical "average" C++ programmer to use the library successfully?
+
+
+ Appropriate topics for documentation often include:
+
+
+
+ - General introduction to the library.
+
+ - Description of each class.
+
+ - Relationship between classes.
+
+ - For each function, as applicable, description, requirements
+ (preconditions), effects, post-conditions, returns, and throws.
+
+ - Discussion of error detection and recovery strategy.
+
+
+ - How to use including description of typical uses.
+
+ - How to compile and link.
+
+ - How to test.
+
+ - Version or revision history.
+
+ - Rationale for design decisions. See Rationale rationale.
+
+
+ - Acknowledgements. See Acknowledgments
+ rationale.
+
+
+
+ If you need more help with how to write documentation you can check out the
+ article on Writing Documentation for
+ Boost.
+
+
+
+
+ Rationale for some of the requirements and guidelines follows.
+
+
+
+
+
+ Exception specifications [ISO 15.4] are sometimes coded to indicate what
+ exceptions may be thrown, or because the programmer hopes they will
+ improved performance. But consider the following member from a smart
+ pointer:
+
+
+ T& operator*() const throw() { return *ptr; }
+
+
+ This function calls no other functions; it only manipulates fundamental
+ data types like pointers Therefore, no runtime behavior of the
+ exception-specification can ever be invoked. The function is
+ completely exposed to the compiler; indeed it is declared inline Therefore,
+ a smart compiler can easily deduce that the functions are incapable of
+ throwing exceptions, and make the same optimizations it would have made
+ based on the empty exception-specification. A "dumb" compiler, however, may
+ make all kinds of pessimizations.
+
+
+
+ For example, some compilers turn off inlining if there is an
+ exception-specification. Some compilers add try/catch blocks. Such
+ pessimizations can be a performance disaster which makes the code unusable
+ in practical applications.
+
+
+ Although initially appealing, an exception-specification tends to have
+ consequences that require very careful thought to understand. The
+ biggest problem with exception-specifications is that programmers use them
+ as though they have the effect the programmer would like, instead of the
+ effect they actually have.
+
+
+
+ A non-inline function is the one place a "throws nothing"
+ exception-specification may have some benefit with some compilers.
+
+
+
+ Naming conventions rationale
+
+
+ The C++ standard committee's Library Working Group discussed this issue in
+ detail, and over a long period of time. The discussion was repeated again
+ in early boost postings. A short summary:
+
+
+
+ - Naming conventions are contentious, and although several are widely
+ used, no one style predominates.
+
+ - Given the intent to propose portions of boost for the next revision of
+ the C++ standard library, boost decided to follow the standard library's
+ conventions.
+
+ - Once a library settles on a particular convention, a vast majority of
+ stakeholders want that style to be consistently used.
+
+
+
+
+
+ Source code fonts rationale
+
+
+ Dave Abrahams comments: An important purpose (I daresay the primary
+ purpose) of source code is communication: the documentation of intent. This
+ is a doubly important goal for boost, I think. Using a fixed-width font
+ allows us to communicate with more people, in more ways (diagrams are
+ possible) right there in the source. Code written for fixed-width fonts
+ using spaces will read reasonably well when viewed with a variable-width
+ font, and as far as I can tell every editor supporting variable-width fonts
+ also supports fixed width. I don't think the converse is true.
+
+
+
+ Tabs rationale
+
+
+
+ Tabs are banned because of the practical problems caused by tabs in
+ multi-developer projects like Boost, rather than any dislike in principle.
+ See mailing list archives. Problems
+ include maintenance of a single source file by programmers using tabs and
+ programmers using spaces, and the difficulty of enforcing a consistent tab
+ policy other than just "no tabs". Discussions concluded that Boost files
+ should either all use tabs, or all use spaces, and thus the decision to
+ stick with spaces.
+
+
+
+ ECMAScript/JavaScript rationale
+
+
+
+ Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript
+ documentation. Controversy followed (see mailing list archives), and the developers
+ were asked to remove the ECMAScript/JavaScript. Reasons given for banning
+ included:
+
+
+ - Incompatible with some older browsers and some text based browsers.
+
+ - Makes printing docs pages difficult.
+
+ - Often results in really bad user interface design.
+
+
+ - "It's just annoying in general."
+
+ - Would require Boost to test web pages for ECMAScript/JavaScript
+ compliance.
+
+ - Makes docs maintenance by other than the original developer more
+ difficult.
+
+
+
+
+
+ Rationale is defined as "The fundamental reasons for something; basis" by
+ the American Heritage Dictionary.
+
+
+ Beman Dawes comments: Failure to supply contemporaneous rationale for
+ design decisions is a major defect in many software projects. Lack of
+ accurate rationale causes issues to be revisited endlessly, causes
+ maintenance bugs when a maintainer changes something without realizing it
+ was done a certain way for some purpose, and shortens the useful lifetime
+ of software.
+
+
+ Rationale is fairly easy to provide at the time decisions are made, but
+ very hard to accurately recover even a short time later.
+
+
+
+
+
+ As a library matures, it almost always accumulates improvements suggested
+ to the authors by other boost members. It is a part of the culture of
+ boost.org to acknowledge such contributions, identifying the person making
+ the suggestion. Major contributions are usually acknowledged in the
+ documentation, while minor fixes are often mentioned in comments within the
+ code itself.
+
+
+
+
+ Revised
+
+ 04 November, 2003
+
+
+ © Copyright Beman Dawes 2003.
+
+
+
+ Distributed under the Boost Software License, Version 1.0. (See
+ accompanying file LICENSE_1_0.txt or copy
+ at www.boost.org/LICENSE_1_0.txt)
+
+