Context Navigation

Changes between Version 1 and Version 2 of Guidelines/Requirements

Timestamp:: Feb 14, 2010, 11:55:11 AM (13 years ago)
Author:: Daniel James
Comment:: Various wiki fixes

Legend:

: Unmodified
: Added
: Removed
: Modified

Guidelines/Requirements

-              v1
+              v2
 library being rejected, it must meets these requirements:
  *  The license must meet the [#License license requirements]
     below. Restricted licenses like the GPL and
     LGPL are not acceptable.
  *  The copyright [#Ownership ownership] must be
     clear.
  *  The library must be generally useful and not restricted
     to a narrow problem domain.
  *  The library must meet the [#Portability portability requirements] below.
  *  The library must come reasonably close to meeting the
     [#Guidelines Guidelines] below.
      *  [#Design_and_Programming Design and Programming]
      *  [#Directory_structure Directory Structure]
      *  [#Documentation Documentation]
  *  The author must be willing to participate in discussions
     on the mailing list, and to refine the library
     accordingly.
+ * The license must meet the [#License license requirements]
+   below. Restricted licenses like the GPL and
+   LGPL are not acceptable.
+ * The copyright [#Ownership ownership] must be
+   clear.
+ * The library must be generally useful and not restricted
+   to a narrow problem domain.
+ * The library must meet the [#Portability portability requirements] below.
+ * The library must come reasonably close to meeting the
+   [#Guidelines Guidelines] below.
+   * [#Design_and_Programming Design and Programming]
+   * [#Directory_structure Directory Structure]
+   * [#Documentation Documentation]
+ * 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
 …
 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.
+ * 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.
 === Portability requirements === #Portability
  *  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
     [http://www.boost.org/doc/libs/release/libs/config/config.htm configuration header]
     is the preferred mechanism for working around
     compiler deficiencies.
+ * 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
+   [http://www.boost.org/doc/libs/release/libs/config/config.htm configuration header]
+   is the preferred mechanism for working around
+   compiler deficiencies.
 Since there is no absolute way to prove portability, many
 …
 Read the
 [http://www.boost.org/development/separate_compilation.html guidelines for libraries with separate source]
+ to see how to ensure that
+compiled link libraries meet user expectations.
+to see how to ensure that compiled link libraries meet user expectations.
 Use the naming conventions of the C++ Standard Library (See
 [#Naming 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_`.
+ * 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,
 …
 guidelines:
  *  Use fixed-width fonts. See [#code_fonts fonts rationale].
  *  Use spaces rather than tabs. See [#Tabs tabs rationale].
  *  Limit line lengths to 80 characters.
+ * Use fixed-width fonts. See [#code_fonts fonts rationale].
+ * Use spaces rather than tabs. See [#Tabs tabs rationale].
+ * Limit line lengths to 80 characters.
 End all documentation files (HTML or otherwise) with a
 …
 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
     [http://www.boost.org/users/license.html 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.
+ * A comment line describing the contents of the file.
+ * Comments describing copyright and licensing: again, the
+   preferred form is indicated in the
+   [http://www.boost.org/users/license.html 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
 …
 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.
+ * 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.
 === Directory Structure and Filenames === #Directory_structure
 …
 choice.
  *  Names must contain only
     '''lowercase'''^[#Filename_rationale_1 1]^ ASCII letters
     (`'a'`-`'z'`), numbers
     (`'0'`-`'9'`), underscores
     (`'_'`), hyphens (`'-'`), and periods
     (`'.'`). Spaces are not allowed^[#Filename_rationale_2 2]^.
  *  Directory names must not contain periods
     (`'.'`)^[#Filename_Rationale_3 3]^.
  *  The first and last character of a file name must not be a
     period (`'.'`)^[#Filename_rationale_4 4]^.
  *  The first character of names must not be a hyphen
     (`'-'`)^[#Filename_rationale_5 5]^.
  *  The maximum length of directory and file names is 31
     characters^[#Filename_rationale_6 6]^.
  *  The total path length must not exceed 207
     characters^[#Filename_rationale_7 7]^.
+ * Names must contain only
+   '''lowercase'''^[#Filename_rationale_1 1]^ ASCII letters
+   (`'a'`-`'z'`), numbers
+   (`'0'`-`'9'`), underscores
+   (`'_'`), hyphens (`'-'`), and periods
+   (`'.'`). Spaces are not allowed^[#Filename_rationale_2 2]^.
+ * Directory names must not contain periods
+   (`'.'`)^[#Filename_Rationale_3 3]^.
+ * The first and last character of a file name must not be a
+   period (`'.'`)^[#Filename_rationale_4 4]^.
+ * The first character of names must not be a hyphen
+   (`'-'`)^[#Filename_rationale_5 5]^.
+ * The maximum length of directory and file names is 31
+   characters^[#Filename_rationale_6 6]^.
+ * The total path length must not exceed 207
+   characters^[#Filename_rationale_7 7]^.
 Other conventions ease communication:
  *  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 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).
+ * 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 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 ==== #subdirectory
 …
 "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''.
+ * 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.
+ * 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.
+ * 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.
 === Documentation === #Documentation
 …
 Appropriate topics for documentation often include:
  *  General introduction to the library. The introduction
     particularly needs to include:
      *  A very high-level overview of what the library is
         good for, and perhaps what it isn't good for,
         understandable even by those with no prior knowledge of
         the problem domain.
      *  The simplest possible ("hello world") example of
         using the library.
  *  Tutorial covering basic use cases.
  *  Reference documentation:
      *  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 compile and link.
  *  How to test.
  *  Version or revision history.
  *  Rationale for design decisions. See [#Rationale Rationale rationale].
  *  Acknowledgements. See [#Acknowledgements Acknowledgments rationale.]
+ * General introduction to the library. The introduction
+   particularly needs to include:
+   * A very high-level overview of what the library is
+    good for, and perhaps what it isn't good for,
+    understandable even by those with no prior knowledge of
+    the problem domain.
+    * The simplest possible ("hello world") example of
+      using the library.
+ * Tutorial covering basic use cases.
+ * Reference documentation:
+   * 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 compile and link.
+ * How to test.
+ * Version or revision history.
+ * Rationale for design decisions. See [#Rationale Rationale rationale].
+ * Acknowledgements. See [#Acknowledgements Acknowledgments rationale.]
 If you need more help with how to write documentation you
 …
 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.
+ * 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 === #code_fonts
 …
 === Directory and File Names rationale === #FileNamesRat
+. Some legacy file systems require
+    single-case names. Single-case names eliminate casing mistakes
+    when moving from case-insensitive to case-sensitive file
+    systems.
+. 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."
+. Strict implementations of ISO
+: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.
+. POSIX has special rules for names
+    beginning with a period. Windows prohibits names ending in a
+    period.
+. Would be too confusing or ambiguous in certain contexts.
+. 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.
+. ISO 9660:1999.
+{{{
+#!html
+<a name="Filename_rationale_1" id="Filename_rationale_1"></a>
+}}}
+. Some legacy file systems require
+single-case names. Single-case names eliminate casing mistakes
+when moving from case-insensitive to case-sensitive file
+systems.
+{{{
+#!html
+<a name="Filename_rationale_2" id="Filename_rationale_2"></a>
+}}}
+. 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."
+{{{
+#!html
+<a name="Filename_rationale_3" id="Filename_rationale_3"></a>
+}}}
+.Strict implementations of ISO
+: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.
+{{{
+#!html
+<a name="Filename_rationale_4" id="Filename_rationale_4"></a>
+}}}
+. POSIX has special rules for names
+beginning with a period. Windows prohibits names ending in a
+period.
+{{{
+#!html
+<a name="Filename_rationale_5" id="Filename_rationale_5"></a>
+}}}
+.Would be too confusing or ambiguous in certain contexts.
+{{{
+#!html
+<a name="Filename_rationale_6" id="Filename_rationale_6"></a>
+}}}
+.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.
+{{{
+#!html
+<a name="Filename_rationale_7" id="Filename_rationale_7"></a>
+}}}
+.ISO 9660:1999.
 === ECMAScript/JavaScript rationale === #JavaScript
 …
 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.
+ * 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 rationale === #Rationale_rationale
 …
 documentation, while minor fixes are often mentioned in
 comments within the code itself.
+Copyright Beman Dawes, 2003.