From 9a32a6dffe6cd1af03926dd4ea25be016e1dc2c8 Mon Sep 17 00:00:00 2001 From: Rene Rivera Date: Wed, 6 Jan 2016 07:04:46 -0600 Subject: [PATCH] New structure and integration requirements. Rewrite structure requirements, add integration requirements, and general cleanup to further the modularity of libraries and ease tool development and maintenance. --- development/requirements.html | 1444 ++++++++++++++++++++------------- 1 file changed, 863 insertions(+), 581 deletions(-) diff --git a/development/requirements.html b/development/requirements.html index 840936fb..520ff68d 100644 --- a/development/requirements.html +++ b/development/requirements.html @@ -3,14 +3,15 @@ - Boost Library Requirements and Guidelines - - - - - @@ -33,468 +34,231 @@ http://www.boost.org/development/website_updating.html + +
  • Guidelines -
    • + -
  • - Rationale +
  • Rationale -
    • + rationale + -

    Introduction

    +

    + Introduction +

    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. +

    -

    Requirements

    +

    + Requirements +

    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.

    -

    License - requirements

    +

    + 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 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:

    -

    Portability - requirements

    +

    + Portability + 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.

    -

    Ownership

    +

    + Ownership +

    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.

    -

    Guidelines

    +

    + Organization +

    -

    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:

    -

    Design and Programming

    - -

    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):

    - - - -

    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:

    - - - -

    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:

    - - - -

    Directory Structure and - Filenames

    - -

    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.

    - - - -

    Other conventions ease communication:

    - - - - - +
    - Boost standard sub-directory names -
    + - + @@ -506,17 +270,29 @@ http://www.boost.org/development/website_updating.html - + - + + + + + + + + + - + @@ -524,41 +300,504 @@ http://www.boost.org/development/website_updating.html - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + library. - + - + - + + + + + + + + +
    Boost standard library organization
    Sub-directorySub-directory or file Contents
    buildLibrary 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.
    docSources 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/htmlDocumentation (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.htmlRedirection 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.
    metaMeta-data about the library.Required for all libraries.
    meta/libraries.jsonContains 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.If any source files.Required if the library has source files to build.
    testRegression 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.
    toolsTools 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.
    -

    Redirection

    +

    + Integration +

    -

    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:

    +
    +
    Building Sources
    +
    +

    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 ;
    +

    +
    +
    Testing
    +
    +

    + 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: +

    +
      +
    • minimal - Tests that are quick to perform. + They are only run durgin the continuous integration + testing.
      • +
    • full - The minimal tests, plus + additional tests to do resonably full coverave for full + regression testing. These are run on the non-CI dedicated + testing machines (and possible on some CI setups).
      • +
    • extra - Additional tests, not including + the full tests, that provide testing for optional + features, or relevant to particular users.
      • +
    +

    + 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.

    +
    +
    Building Documentation
    +
    +

    + 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: +

    +
      +
    1. Define a boostboost target. This target + should likely be an alias that looks roughly like:
      + 
      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 ;
      2. +
    2. The project must default to building standalone + documentation if it has any. The release scripts build + this default so as to guarantee all projects have up to + date documentation.
      3. +
    +
    +
    + +

    + Guidelines +

    + +

    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.

    + +

    + Design + and Programming +

    + +

    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): +

    + + + +

    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:

    + + + +

    + 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: +

    + + + +

    + Filenames +

    + +

    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.

    + + + +

    Other conventions ease communication:

    + + + +

    + Redirection +

    + +

    + 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>
    -

    Naming consistency

    +

    + Naming + consistency +

    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:

    -

    Documentation

    +

    + Documentation +

    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:

    @@ -700,161 +941,191 @@ http://www.boost.org/development/website_updating.html
  • Version or revision history.
    • -
  • Rationale for design decisions. See Rationale rationale.
    • +
  • Rationale for design decisions. See Rationale rationale. +
    • -
  • Acknowledgements. See Acknowledgments 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.

    +

    + If you need more help with how to write documentation you can + check out the article on Writing + Documentation for Boost. +

    -

    Rationale

    +

    + Rationale +

    Rationale for some of the requirements and guidelines - follows.

    + follows.

    -

    Exception-specification - rationale

    +

    + Exception-specification + rationale +

    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.

    -

    Naming conventions - rationale

    +

    + 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:

    +

    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:

    -

    Source code fonts - rationale

    +

    + 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.

    + 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 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.

    +

    + 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. +

    -

    Directory and - File Names rationale

    +

    + Directory and File + Names rationale +

    -

    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. +

    -

    ECMAScript/JavaScript rationale

    +

    + 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:

    +

    + 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: +

    -

    Rationale rationale

    +

    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 + rationale +

    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.

    -

    Acknowledgements rationale

    +

    + Acknowledgements + rationale +

    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; }