This page describes requirements and guidelines for the - content of a library submitted to Boost.
+ content of a library submitted to Boost. -See the Boost Library Submission - Process page for a description of the process involved.
++ 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:
+ library being rejected, it must meet these requirements: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.
+ 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 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:
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.
+ 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:
+ 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.
+ 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.
+ 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.
+The quality of the Boost libraries is not just about the + APIs and code design. But also about presenting a consistent + view to users of the libraries as a whole. Upon acceptance + libraries must adhere to this directory and file structure:
-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.
- -Headers should be good neighbors. See the header policy. See Naming consistency.
- -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.
- -Read Implementation - Variation to see how to supply performance, platform, or - other implementation variations.
- -Browse through - the Best Practices Handbook for ideas and links to source - code in existing Boost libraries.
- -Read the guidelines for - libraries with separate source to see how to ensure that - compiled link libraries meet user expectations.
- -Use the naming conventions of the C++ Standard Library (See - Naming conventions rationale):
- -xml_parser instead of
- XML_parser).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.
- -Avoid exception-specifications. See exception-specification - rationale.
- -Provide sample programs or confidence tests so potential - users can see how to use your library.
- -Provide a regression test program or programs which follow - the Test Policies and - Protocols.
- -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 license information page for the - preferred form.
- -Begin all source files (including programs, headers, - scripts, etc.) with:
- -LICENSE_1_0.txt with their libraries: Boost
- distributions already include a copy in the Boost root
- directory.-// 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.
Assertions: If you want to add runtime
- assertions to your code (you should!), avoid C's
- assert macro and use Boost's
- BOOST_ASSERT macro (in
- boost/assert.hpp) instead. It is more
- configurable. Use BOOST_ASSERT in public headers
- and in library source code (for separately compiled libraries).
- Use of C's assert macro is ok in examples and in
- documentation.
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:
std::min() or
- std::max():
-
- (std::min)(a,b).#include
- <boost/config.hpp>BOOST_USING_STD_MIN(); to bring
- std::min() into the current scope.min BOOST_PREVENT_MACRO_SUBSTITUTION
- (a,b); to make an argument-dependent call to
- min(a,b).std::numeric_limits<int>::max(), use
- (std::numeric_limits<int>::max)()
- instead.min() or
- max() member function, instead to doing
- obj.min(), use (obj.min)().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.Naming requirements ensure that file and directory names are - relatively portable, including to ISO 9660:1999 (with - extensions) and other relatively limited file systems. - Superscript links are provided to detailed rationale for each - choice.
- -'a'-'z'), numbers
- ('0'-'9'), underscores
- ('_'), hyphens ('-'), and periods
- ('.'). Spaces are not allowed2.'.')3.'.')4.'-')5.Other conventions ease communication:
- -| Sub-directory | +Sub-directory or file | Contents | @@ -506,17 +270,29 @@ http://www.boost.org/development/website_updating.html||
|---|---|---|---|---|
build |
- Library build files such as a Jamfile. | +Library build files such as a Jamfile, IDE + projects, Makefiles, Cmake files, etc. | -If any build files. | +Required if the library has sources to build. |
doc |
+ Sources to build with and built documentation for + the library. If the library needs to build documentation + from non-HTML files this location must be buildable with + Boost Build. | + +Required for all libraries. | +||
doc/html |
+
Documentation (HTML) files. | -If several doc files. | +Required for all libraries. | |
| Sample program files. | -If several sample files. | +Required if library has sample files. Which is + highly recommended. | +||
index.html |
+
+ Redirection to HTML documentation. See "Redirection" for a template for + this file. + | + +Required for all libraries. | +||
+ include/boost/library
+ |
+
+ Header files for the library. | + +Required for all libraries. | +||
meta |
+
+ Meta-data about the library. | + +Required for all libraries. | +||
meta/libraries.json |
+
+ Contains information about the library used to + generate website and documentation for the Boost C++ + Libraries collection. | + +Required for all libraries. | ||
src |
Source files which must be compiled to build the - library. | + library. -If any source files. | +Required if the library has source files to build. | |
test |
- Regression or other test programs or scripts. | +Regression or other test programs or scripts. This + is the only location considered for automated + testing. If you have additional locations that need to be + part of automated testing it is required that this + location refer to the additional test locations. + | -If several test files. | +Required for all libraries. | +
tools |
+
+ Tools used, or offered, by the library. The + structure within this is up to the library, but it's + recommended to use similar structure as a regular Boost + library or tool. | + +Required for libraries that have runable tools. |
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.
++ Once a library is accepted as part of the Boost C++ Libraries it + is required that it integrate properly into the development, + testing, documentation, and release processes. This integration + increases the eventual quality of all the libraries and is + integral to the expected quality of the whole of the Boost C++ + Libraries from users. In addition to the organization + requirements above the following integration is required: +
-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:
+The library needs to provide a Boost Build project that + the user, and the top level Boost project, can use to build + the library if it has sources to build. The Jamfile for the + source build needs to minimally declare the project, the + library target(s), and register the target(s) for + installation. For example:
++
project boost/my_lib ; + +lib boost_my_lib : a.cpp ; + +boost-install boost_my_lib ;+ +
+ The library needs to provide a Boost Build project that the + user, and the root Boost test script, can use to build and + run the tests for the library. The testing build project + must be buildable from the + project-root/test + directory. And must contain the following targets: +
++ You can also define additional targets as you see fit. For + example you might define a + performance + target to run performance measurement tests. +
++ Note, we recommend that the + full + target be the default. For example: +
+using testing ; + +project test ; + +test-suite minimal : [ run a.cpp ] ; +test-suite full : minimal [ compile b.cpp ] ; +test-suite extra : [ run c.cpp ] ; + +explicit minimal ; +explicit extra ;+
WARNING: This is the only location considered for + testing by the top level testing script. If you want to test + additional locations you must declare such that they are + built as dependencies to the above targets.
++ The library needs to provide a Boost Build project for + building the documentation for the library. The + project-root/doc + project is the only location refered to by the top level + documentation build scripts and the release building + scripts. The documentation build project must have the + following two features: +
+alias boostbook : my_boostbook_target + : : : <implicit-dependency>my_boostbook_target ;But if your project + doesn't integrate into the global documentation book you + can use an empty alias like:
alias boostbook ;
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.
+ ++ Headers should be good neighbors. See the header policy. See Naming consistency. +
+ +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. +
+ ++ Read Implementation + Variation to see how to supply performance, platform, or other + implementation variations. +
+ ++ Browse through + the Best Practices Handbook for ideas and links to source code + in existing Boost libraries. +
+ ++ Read the guidelines + for libraries with separate source to see how to ensure that + compiled link libraries meet user expectations. +
+ ++ Use the naming conventions of the C++ Standard Library (See Naming conventions rationale): +
+ +xml_parser
+ instead of XML_parser).
+ 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.
+ ++ Avoid exception-specifications. See exception-specification + rationale. +
+ +Provide sample programs or confidence tests so potential + users can see how to use your library.
+ ++ Provide a regression test program or programs which follow the Test Policies and Protocols. +
+ +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 license information page for + the preferred form. +
+ +Begin all source files (including programs, headers, + scripts, etc.) with:
+ +LICENSE_1_0.txt
+ with their libraries: Boost distributions already include a
+ copy in the Boost root directory.
+ +// 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.
+
+ Assertions: If you want to add runtime
+ assertions to your code (you should!), avoid C's
+ assert
+ macro and use Boost's
+ BOOST_ASSERT
+ macro (in
+ boost/assert.hpp
+ ) instead. It is more configurable. Use
+ BOOST_ASSERT
+ in public headers and in library source code (for separately
+ compiled libraries). Use of C's
+ assert
+ macro is ok in examples and in documentation.
+
+ 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:
+
std::min() or std::max():
+
+ (std::min)(a,b).
+ #include <boost/config.hpp>BOOST_USING_STD_MIN(); to
+ bring std::min() into the current scope.
+ min
+ BOOST_PREVENT_MACRO_SUBSTITUTION (a,b); to make an
+ argument-dependent call to min(a,b).
+ std::numeric_limits<int>::max(),
+ use (std::numeric_limits<int>::max)()
+ instead.
+ min() or max()
+ member function, instead to doing obj.min(), use
+ (obj.min)().
+ 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.
+ Naming requirements ensure that file and directory names + are relatively portable, including to ISO 9660:1999 (with + extensions) and other relatively limited file systems. + Superscript links are provided to detailed rationale for each + choice.
+ +'a'-'z'),
+ numbers ('0'-'9'), underscores ('_'),
+ hyphens ('-'), and periods ('.').
+ Spaces are not allowed2.
+ '.')3.
+ '.')4.
+ '-')5.
+ Other conventions ease communication:
+ ++ The primary directory should always contain a file named + index.html. 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. +
+ +
+ The primary directory
+ index.html
+ file should just do an automatic redirection to the
+ doc/html
+ subdirectory:
+
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
@@ -567,7 +806,7 @@ http://www.boost.org/development/website_updating.html
<head>
<title>Boost.Name Documentation</title>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
- <meta http-equiv="refresh" content="0; URL=doc/index.html" />
+ <meta http-equiv="refresh" content="0; URL=doc/html/index.html" />
</head>
<body>
@@ -577,40 +816,41 @@ http://www.boost.org/development/website_updating.html
</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.
+ 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".
+ 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".When documenting Boost libraries, follow these conventions - (see also the following section of this document):
+ (see also the following section of this document):Here are a few examples of how to apply these - conventions:
+Here are a few examples of how to apply these conventions:
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.
+ 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.
++ 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 discouraged. The + documentation entry point should always be a file named + index.html; 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?
+ 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:
If you need more help with how to write documentation you - can check out the article on Writing - Documentation for Boost.
++ 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.
+ follows. -Exception specifications [ISO 15.4] are sometimes coded to - indicate what exceptions may be thrown, or because the - programmer hopes they will improve performance. But consider - the following member from a smart pointer:
+ indicate what exceptions may be thrown, or because the + programmer hopes they will improve 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.
+ 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.
+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.
++ 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.
+ exception-specification may have some benefit with some + compilers. -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:
+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:
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.
+ 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 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.
++ 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 for indentation. +
-1. Some legacy file systems require - single-case names. Single-case names eliminate casing mistakes - when moving from case-insensitive to case-sensitive file - systems.
++ 1. + Some legacy file systems require single-case names. Single-case + names eliminate casing mistakes when moving from + case-insensitive to case-sensitive file systems. +
-2. This is the lowercase portion of - the POSIX portable filename character set. To quote the POSIX - standard, "Filenames should be constructed from the portable - filename character set because the use of other characters can - be confusing or ambiguous in certain contexts."
++ 2. + This is the lowercase portion of the POSIX portable filename + character set. To quote the POSIX standard, "Filenames should be + constructed from the portable filename character set because the + use of other characters can be confusing or ambiguous in certain + contexts." +
-3. Strict implementations of ISO - 9660:1999 and some legacy operating systems prohibit dots in - directory names. The need for this restriction is fading, and - it will probably be removed fairly soon.
++ 3. + Strict implementations of ISO 9660:1999 and some legacy + operating systems prohibit dots in directory names. The need for + this restriction is fading, and it will probably be removed + fairly soon. +
-4. POSIX has special rules for names - beginning with a period. Windows prohibits names ending in a - period.
++ 4. + POSIX has special rules for names beginning with a period. + Windows prohibits names ending in a period. +
-5. Would be too confusing or - ambiguous in certain contexts.
++ 5. + Would be too confusing or ambiguous in certain contexts. +
-6. We had to draw the line - somewhere, and so the limit imposed by a now obsolete Apple - file system was chosen years ago. It still seems a reasonable - limit to aid human comprehension.
++ 6. + We had to draw the line somewhere, and so the limit imposed by a + now obsolete Apple file system was chosen years ago. It still + seems a reasonable limit to aid human comprehension. +
-7. ISO 9660:1999.
++ 7. + ISO 9660:1999. +
-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:
++ 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: +
Please conside those reasons if you decide that JavaScript + is something you must use. In particular please keep in mind + that the Boost community is not responsible for testing your use + of JavaScript. And hence it is up to you to ensure that the + above issues are fully resolved in your use case.
+ +ECMAScript/JavaScript use is allowed but discouraged for + the reasons above.
+ +Rationale is defined as "The fundamental reasons for - something; basis" by the American Heritage Dictionary.
+ 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 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.
+ 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.
+ 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. @@ -913,13 +1197,11 @@ T& operator*() const throw() { return *ptr; }