more/lib_guide.htm

<html>

<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Library Requirements and Guidelines</title>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta name="Microsoft Border" content="none, default">
</head>

<body bgcolor="#FFFFFF" text="#000000">

<table border="1" bgcolor="#007F7F" cellpadding="2">
  <tr>
    <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
    <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
    <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
    <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
    <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
    <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
  </tr>
</table>
<h1 align="left">Boost Library Requirements and Guidelines</h1>
<p align="left"><a href="#Introduction">Introduction</a><br>
<a href="#Requirements">Requirements</a><br>
&nbsp;&nbsp;&nbsp; <a href="#License">License requirements</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Portability">Portability requirements</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Ownership">Ownership</a><br>
<a href="#Guidelines">Guidelines</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Design_and_Programming">Design and programming</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Directory_structure">Directory structure and 
filenames</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Naming<6E>_consistency">Naming consistency</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Documentation">Documentation</a><br>
<a href="#Rationale">Rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Exception-specification">Exception-specification 
rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Naming">Naming conventions rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#code_fonts">Source code fonts rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Tabs">Tabs rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#JavaScript">ECMAScript/JavaScript rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Rationale_rationale">Rationale rationale</a><br>
&nbsp;&nbsp;&nbsp; <a href="#Acknowledgements">Acknowledgements rationale</a></p>
<h2 align="left"><a name="Introduction">Introduction</a></h2>
<p align="left">This page describes requirements and guidelines for the content
of a library submitted to Boost.</p>
<p align="left">See the <a href="submission_process.htm">Boost Library
Submission Process</a> page for a description of the process involved.</p>
<h2 align="left"><a name="Requirements">Requirements</a></h2>
<p>To avoid the frustration and wasted time of a proposed library being
rejected, it must meets these requirements:</p>
<ul>
  <li>The license must meet the <a href="#License">license requirements</a>
    below. Restricted licenses like the GPL and LGPL are not acceptable.
  </li>
  <li>The
    copyright <a href="#Ownership">ownership</a> must be clear.
  </li>
  <li>The library must be generally useful and not restricted to a narrow
    problem domain.
  </li>
  <li>The library must meet the <a href="#Portability">portability requirements</a>
    below.&nbsp;
  </li>
  <li>The library must come reasonably close to meeting the <a href="#Guidelines">Guidelines</a>
    below.
    <ul>
    <li><a href="#Design_and_Programming">Design and Programming</a></li>
    <li><a href="#Directory_structure">Directory Structure</a></li>
    <li><a href="#Documentation">Documentation</a></li>
    </ul>
  </li>
  <li>The author must be willing to participate in discussions on the mailing
    list, and to refine the library accordingly.</li>
</ul>
<p>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
&quot;I just started to read this mailing list ...&quot; seem to fail, often
embarrassingly.</p>
<h3 align="left"><a name="License">License</a> requirements</h3>
<ul>
  <li>Must be simple to read and understand. 
  </li>
  <li>Must grant permission without fee to copy, use and modify the software for 
  any use (commercial and non-commercial).  
  </li>
  <li>Must require that the license appear on all copies of the software source 
  code. 
  </li>
  <li>Must not require that the license appear with executables or other binary 
  uses of the library. 
  </li>
  <li>Must not require that the source code be available for execution or other 
  binary uses of the library. 
  </li>
  <li>May restrict the use of the name and description of the library to the 
  standard version found on the Boost web site.</li>
</ul>
<p>The preferred way to meet these license requirements is to use the
<a href="../LICENSE">Boost Software License</a>. See <a href="license_info.html">
license information</a>. If for any reason you do not intend to use the Boost 
Software License, please discuss the issues on the Boost
<a href="mailing_lists.htm#main">developers mailing list</a> first.</p>
<h3 align="left"><a name="Portability">Portability</a> requirements</h3>
<ul>
  <li>
    <p align="left">A library's interface must portable and not restricted to a
    particular compiler or operating system.
  </li>
  <li>
    <p align="left">A library's implementation must if possible be portable and
    not restricted to a particular compiler or operating system.&nbsp; 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).
  </li>
  <li>
    <p align="left">There is no requirement that a library run on C++ compilers
    which do not conform to the ISO standard.&nbsp;
  </li>
  <li>
    <p align="left">There is no requirement that a library run on any particular
    C++ compiler.&nbsp; Boost contributors often try to ensure their libraries
    work with popular compilers.&nbsp; The boost/config.hpp <a href="../libs/config/config.htm">configuration
    header</a> is the preferred mechanism for working around compiler
    deficiencies.</li>
</ul>
<p align="left">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.&nbsp; Otherwise reviewers may disbelieve that porting is in fact
practical.</p>
<h3 align="left"><a name="Ownership">Ownership</a></h3>
<p align="left">Are you sure you own the library you are thinking of
submitting?&nbsp;&nbsp; &quot;How to Copyright Software&quot; by MJ Salone, Nolo
Press, 1990 says:</p>
<blockquote>
  <p align="left">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.&nbsp; In this situation, it's best to get a written release from
  your employer in advance.</p>
</blockquote>
<p align="left">Place a copyright notice in all the important files you submit.
Boost won't accept libraries without clear copyright information.</p>
<h2 align="left"><a name="Guidelines">Guidelines</a></h2>
<p align="left">Please use these guidelines as a checklist for preparing the
content a library submission.&nbsp; Not every guideline applies to every
library, but a reasonable effort to comply is expected.</p>
<h3><a name="Design_and_Programming">Design and Programming</a></h3>
<ul>
  <li>Aim first for clarity and correctness; optimization should be only a
    secondary concern in most Boost libraries.</li>
</ul>
<ul>    
  <li>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.</li>
</ul>
<ul>
  <li>Headers should be good neighbors. See the <a href="header.htm">header
    policy</a>. See <a href="#Naming<6E>_consistency">Naming consistency</a>.</li>
</ul>
<ul>
  <li>Follow quality programming practices. See, for example, &quot;Effective
    C++&quot; 2nd Edition, and &quot;More Effective C++&quot;, both by Scott
    Meyers, published by Addison Wesley.</li>
</ul>
<ul>
  <li>Use the C++ Standard Library or other Boost libraries, but only when the
    benefits outweigh the costs.&nbsp; Do not use libraries other than the C++
    Standard Library or Boost. See <a href="library_reuse.htm">Library reuse</a>.</li>
</ul>
<ul>
  <li>Read <a href="imp_vars.htm">Implementation Variation</a> to see how to
    supply performance, platform, or other implementation variations.</li>
</ul>
<ul>
  <li>Use the naming conventions of the C++ Standard Library (See
  <a href="#Naming">Naming conventions rationale</a>): <br>
&nbsp;<ul>
  <li>Names (except as noted below) should be all lowercase, with words 
  separated by underscores.</li>
  <li>Acronyms should be treated as ordinary names (e.g. <code>xml_parser</code> instead of <code>XML_parser</code>).</li>
  <li>Template parameter names begin with an uppercase letter.</li>
  <li>Macro (gasp!) names all uppercase and begin with BOOST_.</li>
</ul>
  </li>
</ul>
<ul>
  <li>Choose meaningful names - explicit is better than implicit, and readability counts.
    There is a strong preference for clear and descriptive names, even if
    lengthy.</li>
</ul>
<ul>
  <li>Use exceptions to report errors where appropriate, and write code that is
    safe in the face of exceptions.</li>
</ul>
<ul>
  <li>Avoid exception-specifications. See <a href="#Exception-specification">exception-specification
    rationale</a>.</li>
</ul>
<ul>
  <li>Provide sample programs or confidence tests so potential users can see how
    to use your library.</li>
</ul>
<ul>
  <li>Provide a regression test program or programs which follow the <a href="test_policy.htm">Test
    Policies and Protocols</a>.</li>
</ul>
<ul>
  <li>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:
    <ul>
      <li>Use fixed-width fonts.&nbsp; See <a href="#code_fonts">fonts rationale</a>.</li>
      <li>Use spaces rather than tabs. See <a href="#Tabs">tabs rationale</a>.</li>
      <li>Limit line lengths to 80 characters.</li>
    </ul>
  </li>
</ul>
<ul>
  <li>End all documentation files (HTML or otherwise) with a copyright message 
  and a licensing message. See the <a href="#Copyright">end of this file</a> for 
  an example of the preferred form.</li>
</ul>
<ul>
  <li>Begin all source files (including programs, headers, scripts, etc.) with:
  <br>
&nbsp;<ul>
      <li>A comment line describing the contents of the file.<br>
&nbsp;</li>
      <li>Comments describing copyright and licensing. The preferred form is:<br>
      <br>
        <code>//&nbsp; Copyright Jane Programmer 2002. Use, modification and 
      distribution is<br>
      //&nbsp; subject to the Boost Software License, Version 1.0. (See 
      accompanying<br>
      //&nbsp; file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)<br>
      </code>
        <br>
      Please leave an empty line before and after the copyright and license 
      comments.<br>
      <br>
      See <a href="license_info.html">license information page</a> for 
      more information about the Boost Software License.<br>
&nbsp;</li>
      <li>A comment line referencing your library on the Boost web site. For 
      example:<br>
      <br>
        <code>//&nbsp; See http://www.boost.org/libs/foo for library home page.</code><br>
        <br>
      where <code>foo</code> 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.</li>
    </ul>
  </li>
</ul>
<h3><a name="Directory_structure">Directory Structure</a> and Filenames</h3>
<ul>
  <li>File and directory names must contain only lowercase ASCII letters ,
    numbers, underscores, and a period.&nbsp; Leading character must be
    alphabetic. Maximum length 31. Only a single period is permitted.&nbsp;
    These requirements ensure file and directory names are relatively portable.</li>
  <li>All libraries have at their highest level a primary directory named for
    the particular library. See <a href="#Naming<6E>_consistency">Naming consistency</a>. The primary directory may have sub-directories.</li>
  <li>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).</li>
</ul>
<blockquote>
  <p><b>Boost standard sub-directory names</b></p>
  <table border="1" cellpadding="5">
    <tr>
      <td><b>Sub-directory</b></td>
      <td><b>Contents</b></td>
      <td><b>Required</b></td>
    </tr>
    <tr>
      <td><code>build</code></td>
      <td>Library build files such as a Jamfile.</td>
      <td>If any build files.</td>
    </tr>
    <tr>
      <td>doc</td>
      <td>Documentation (HTML) files.</td>
      <td>If several doc files.</td>
    </tr>
    <tr>
      <td><code>example</code></td>
      <td>Sample program files.</td>
      <td>If several sample files.</td>
    </tr>
    <tr>
      <td><code>src</code></td>
      <td>Source files which must be compiled to build the library.&nbsp;</td>
      <td>If any source files.</td>
    </tr>
    <tr>
      <td><code>test</code></td>
      <td>Regression or other test programs or scripts.</td>
      <td>If several test files.</td>
    </tr>
  </table>
</blockquote>
<h4><a name="Redirection">Redirection</a></h4>
<p>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 <i>http://www.boost.org/libs/lib-name</i> 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.</p>
<p>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:</p>
<blockquote>
  <pre>&lt;html&gt;
&lt;head&gt;
&lt;meta http-equiv=&quot;refresh&quot; content=&quot;0; URL=doc/index.html&quot;&gt;
&lt;/head&gt;
&lt;body&gt;
Automatic redirection failed, please go to
&lt;a href=&quot;doc/index.html&quot;&gt;doc/index.html&lt;/a&gt;
&lt;/body&gt;
&lt;/html&gt;</pre>
</blockquote>
<h3><a name="Naming<6E>_consistency">Naming consistency</a></h3>
<p>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 which need their own header subdirectories and 
namespaces.</p>
<p>Here is how it works. The library is given a name which describes the 
contents of the library.&nbsp; Cryptic abbreviations are not acceptable. 
Following the practice of the C++ Standard Library, names are usually singular 
rather than plural.&nbsp; For example, a library dealing with file systems might 
chose the name &quot;filesystem&quot;, but not &quot;filesystems&quot;, &quot;fs&quot; or &quot;nicecode&quot;.</p>
<ul>
  <li>The library's primary directory (in parent <i>boost-root/libs</i>) is 
  given that same name.&nbsp; For example, <i>boost-root/libs/filesystem</i>.<br>
&nbsp;</li>
  <li>The library's primary header directory (in parent <i>boost-root/boost</i>) 
  is given that same name. For example, <i>boost-root/boost/filesystem</i>.<br>
&nbsp;</li>
  <li>The library's primary namespace (in parent <i>::boost</i>) is given that 
  same name. For example, <i>::boost::filesystem</i>.</li>
</ul>
<h3><a name="Documentation">Documentation</a></h3>
<p>Even the simplest library needs some documentation; the amount should be
proportional to the need.&nbsp; The documentation should assume the readers have
a basic knowledge of C++, but are not necessarily experts.</p>
<p>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 <a href="#Redirection">
Redirection</a>.</p>
<p>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 &quot;average&quot;
C++ programmer to use the library successfully?</p>
<p>Appropriate topics for documentation often include:
<ul>
  <li>General introduction to the library.</li>
  <li>Description of each class.</li>
  <li>Relationship between classes.</li>
  <li>For each function, as applicable, description, requirements (preconditions), 
    effects, post-conditions, returns, and throws.</li>
  <li>Discussion of error detection and recovery strategy.</li>
  <li>How to use including description of typical uses.</li>
  <li>How to compile and link.</li>
  <li>How to test.</li>
  <li>Version or revision history.</li>
  <li>Rationale for design decisions.&nbsp; See <a href="#Rationale">Rationale 
    rationale</a>.</li>
  <li>Acknowledgements.&nbsp; See <a href="#Acknowledgements">Acknowledgments 
    rationale.</a></li>
</ul>
<p>If you need more help with how to write documentation you can check out the 
  article on <a href="writingdoc/index.html">Writing Documentation for Boost</a>.</p>
<h2><a name="Rationale">Rationale</a></h2>
<p>Rationale for some of the requirements and guidelines follows.</p>
<hr>
<h3><a name="Exception-specification">Exception-specification</a> rationale</h3>
<p>Exception specifications [ISO 15.4] are sometimes coded to indicate what
exceptions may be thrown, or because the programmer hopes they will improved
performance.&nbsp; But consider the following member from a smart pointer:</p>
<pre>    T&amp; operator*() const throw()  { return *ptr; }</pre>
<p>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.&nbsp; 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 &quot;dumb&quot; compiler, however, may make
all kinds of pessimizations.</p>
<p>For example, some compilers turn off inlining if there is an
exception-specification.&nbsp; Some compilers add try/catch blocks. Such
pessimizations can be a performance disaster which makes the code unusable in
practical applications.</p>
<p>Although initially appealing, an exception-specification tends to have
consequences that require <b>very</b> 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.</p>
<p>A non-inline function is the one place a &quot;throws nothing&quot;
exception-specification may have some benefit with some compilers.</p>
<hr>
<h3><a name="Naming">Naming</a> conventions rationale</h3>
<p>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:</p>
<ul>
  <li>Naming conventions are contentious, and although several are widely used,
    no one style predominates.
  </li>
  <li>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.
  </li>
  <li>Once a library settles on a particular convention, a vast majority of
    stakeholders want that style to be consistently used.
  </li>
</ul>
<hr>
<h3>Source <a name="code_fonts">code fonts</a> rationale</h3>
<p>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.</p>
<hr>
<h3><a name="Tabs">Tabs</a> rationale</h3>
<p>Tabs are banned because of the practical problems caused by tabs in 
multi-developer projects like Boost, rather than any dislike in principle. See
<a href="mailing_lists.htm#archive">mailing list archives</a>. 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 &quot;no tabs&quot;. Discussions concluded that Boost files should either all use 
tabs, or all use spaces, and thus the decision to stick with spaces.</p>
<hr>
<h3>ECMAScript/<a name="JavaScript">JavaScript</a> rationale</h3>
<p>Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript 
documentation. Controversy followed (see <a href="mailing_lists.htm#archive">
mailing list archives</a>), and the developers were asked to remove the 
ECMAScript/JavaScript. Reasons given for banning included:</p>
<ul>
  <li>Incompatible with some older browsers and some text based browsers.</li>
  <li>Makes printing docs pages difficult.</li>
  <li>Often results in really bad user interface design.</li>
  <li>&quot;It's just annoying in general.&quot;</li>
  <li>Would require Boost to test web pages for ECMAScript/JavaScript 
  compliance.</li>
  <li>Makes docs maintenance by other than the original developer more 
  difficult.</li>
</ul>
<hr>
<h3><a name="Rationale_rationale">Rationale rationale</a></h3>
<p>Rationale is defined as &quot;The fundamental reasons for something;
basis&quot; by the American Heritage Dictionary.</p>
<p>Beman Dawes comments:&nbsp; 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.</p>
<p>Rationale is fairly easy to provide at the time decisions are made, but very
hard to accurately recover even a short time later.</p>
<hr>
<h3><a name="Acknowledgements">Acknowledgements</a> rationale</h3>
<p>As a library matures, it almost always accumulates improvements suggested to
the authors by other boost members.&nbsp; It is a part of the culture of
boost.org to acknowledge such contributions, identifying the person making the
suggestion.&nbsp; Major contributions are usually acknowledged in the
documentation, while minor fixes are often mentioned in comments within the code
itself.</p>
<hr>
<p>Revised 
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->02 October, 2003<!--webbot bot="Timestamp" endspan i-checksum="38549" --></p>

<p> <20> <a name="Copyright">Copyright</a> Beman Dawes 2003.</p>
<p> Use, modification, and distribution is subject to the Boost Software 
License, Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt">
LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
www.boost.org/LICENSE_1_0.txt</a>)</p>

</body>

</html>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<html>
 								<head>
 								<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-												prefix "Boost" to the HTML titles for context-free identification


[SVN r8868]

											
										
										
											2001-02-03 03:58:57 +08:00
+								<title>Boost Library Requirements and Guidelines</title>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<meta name="ProgId" content="FrontPage.Editor.Document">
 								<meta name="Microsoft Border" content="none, default">
 								</head>
 								<body bgcolor="#FFFFFF" text="#000000">
 								<table border="1" bgcolor="#007F7F" cellpadding="2">
 								  <tr>
 								    <td bgcolor="#FFFFFF"><img src="../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
 								    <td><a href="../index.htm"><font face="Arial" color="#FFFFFF"><big>Home</big></font></a></td>
-												libraries.htm and people.htm moved to sub-directories to make root directory cleaner.


[SVN r8166]

											
										
										
											2000-11-10 23:39:05 +08:00
+								    <td><a href="../libs/libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries</big></font></a></td>
 								    <td><a href="../people/people.htm"><font face="Arial" color="#FFFFFF"><big>People</big></font></a></td>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								    <td><a href="faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ</big></font></a></td>
 								    <td><a href="index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
 								  </tr>
 								</table>
 								<h1 align="left">Boost Library Requirements and Guidelines</h1>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								<p align="left"><a href="#Introduction">Introduction</a><br>
 								<a href="#Requirements">Requirements</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#License">License requirements</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#Portability">Portability requirements</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#Ownership">Ownership</a><br>
 								<a href="#Guidelines">Guidelines</a><br>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								&nbsp;&nbsp;&nbsp; <a href="#Design_and_Programming">Design and programming</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#Directory_structure">Directory structure and
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								filenames</a><br>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								&nbsp;&nbsp;&nbsp; <a href="#Naming<6E>_consistency">Naming consistency</a><br>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								&nbsp;&nbsp;&nbsp; <a href="#Documentation">Documentation</a><br>
 								<a href="#Rationale">Rationale</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#Exception-specification">Exception-specification
 								rationale</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#Naming">Naming conventions rationale</a><br>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								&nbsp;&nbsp;&nbsp; <a href="#code_fonts">Source code fonts rationale</a><br>
-												Add tabs and JavaScript rationale


[SVN r15252]

											
										
										
											2002-09-10 22:13:01 +08:00
+								&nbsp;&nbsp;&nbsp; <a href="#Tabs">Tabs rationale</a><br>
 								&nbsp;&nbsp;&nbsp; <a href="#JavaScript">ECMAScript/JavaScript rationale</a><br>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								&nbsp;&nbsp;&nbsp; <a href="#Rationale_rationale">Rationale rationale</a><br>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								&nbsp;&nbsp;&nbsp; <a href="#Acknowledgements">Acknowledgements rationale</a></p>
 								<h2 align="left"><a name="Introduction">Introduction</a></h2>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p align="left">This page describes requirements and guidelines for the content
 								of a library submitted to Boost.</p>
 								<p align="left">See the <a href="submission_process.htm">Boost Library
 								Submission Process</a> page for a description of the process involved.</p>
-												Add bookmark


[SVN r11583]

											
										
										
											2001-11-05 21:41:05 +08:00
+								<h2 align="left"><a name="Requirements">Requirements</a></h2>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p>To avoid the frustration and wasted time of a proposed library being
 								rejected, it must meets these requirements:</p>
 								<ul>
 								  <li>The license must meet the <a href="#License">license requirements</a>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								    below. Restricted licenses like the GPL and LGPL are not acceptable.
 								  </li>
 								  <li>The
 								    copyright <a href="#Ownership">ownership</a> must be clear.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>The library must be generally useful and not restricted to a narrow
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								    problem domain.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>The library must meet the <a href="#Portability">portability requirements</a>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								    below.&nbsp;
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>The library must come reasonably close to meeting the <a href="#Guidelines">Guidelines</a>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								    below.
 								    <ul>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								    <li><a href="#Design_and_Programming">Design and Programming</a></li>
 								    <li><a href="#Directory_structure">Directory Structure</a></li>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								    <li><a href="#Documentation">Documentation</a></li>
 								    </ul>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>The author must be willing to participate in discussions on the mailing
 								    list, and to refine the library accordingly.</li>
 								</ul>
 								<p>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
 								&quot;I just started to read this mailing list ...&quot; seem to fail, often
 								embarrassingly.</p>
 								<h3 align="left"><a name="License">License</a> requirements</h3>
 								<ul>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								  <li>Must be simple to read and understand.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								  <li>Must grant permission without fee to copy, use and modify the software for
 								  any use (commercial and non-commercial).
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								  <li>Must require that the license appear on all copies of the software source
 								  code.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								  <li>Must not require that the license appear with executables or other binary
 								  uses of the library.
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								  </li>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								  <li>Must not require that the source code be available for execution or other
 								  binary uses of the library.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								  <li>May restrict the use of the name and description of the library to the
 								  standard version found on the Boost web site.</li>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								</ul>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								<p>The preferred way to meet these license requirements is to use the
 								<a href="../LICENSE">Boost Software License</a>. See <a href="license_info.html">
 								license information</a>. If for any reason you do not intend to use the Boost
 								Software License, please discuss the issues on the Boost
 								<a href="mailing_lists.htm#main">developers mailing list</a> first.</p>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<h3 align="left"><a name="Portability">Portability</a> requirements</h3>
 								<ul>
 								  <li>
 								    <p align="left">A library's interface must portable and not restricted to a
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								    particular compiler or operating system.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>
 								    <p align="left">A library's implementation must if possible be portable and
 								    not restricted to a particular compiler or operating system.&nbsp; If a
 								    portable implementation is not possible, non-portable constructions are
-												Tighten requirements on filenames, add review manager duties, reorganize a bit


[SVN r9977]

											
										
										
											2001-04-25 03:49:05 +08:00
+								    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).
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								    <p align="left">There is no requirement that a library run on C++ compilers
 								    which do not conform to the ISO standard.&nbsp;
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>
 								    <p align="left">There is no requirement that a library run on any particular
 								    C++ compiler.&nbsp; Boost contributors often try to ensure their libraries
-												Fix broken links and other HTML changes related to new config system


[SVN r11142]

											
										
										
											2001-09-19 05:24:51 +08:00
+								    work with popular compilers.&nbsp; The boost/config.hpp <a href="../libs/config/config.htm">configuration
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								    header</a> is the preferred mechanism for working around compiler
 								    deficiencies.</li>
 								</ul>
 								<p align="left">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.&nbsp; Otherwise reviewers may disbelieve that porting is in fact
 								practical.</p>
 								<h3 align="left"><a name="Ownership">Ownership</a></h3>
 								<p align="left">Are you sure you own the library you are thinking of
 								submitting?&nbsp;&nbsp; &quot;How to Copyright Software&quot; by MJ Salone, Nolo
 								Press, 1990 says:</p>
 								<blockquote>
 								  <p align="left">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.&nbsp; In this situation, it's best to get a written release from
 								  your employer in advance.</p>
 								</blockquote>
 								<p align="left">Place a copyright notice in all the important files you submit.
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								Boost won't accept libraries without clear copyright information.</p>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<h2 align="left"><a name="Guidelines">Guidelines</a></h2>
 								<p align="left">Please use these guidelines as a checklist for preparing the
 								content a library submission.&nbsp; Not every guideline applies to every
 								library, but a reasonable effort to comply is expected.</p>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								<h3><a name="Design_and_Programming">Design and Programming</a></h3>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<ul>
-												Minor clarifications


[SVN r11484]

											
										
										
											2001-10-31 08:45:00 +08:00
+								  <li>Aim first for clarity and correctness; optimization should be only a
 								    secondary concern in most Boost libraries.</li>
 								</ul>
 								<ul>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  <li>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.</li>
 								</ul>
 								<ul>
 								  <li>Headers should be good neighbors. See the <a href="header.htm">header
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								    policy</a>. See <a href="#Naming<6E>_consistency">Naming consistency</a>.</li>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								</ul>
 								<ul>
 								  <li>Follow quality programming practices. See, for example, &quot;Effective
 								    C++&quot; 2nd Edition, and &quot;More Effective C++&quot;, both by Scott
 								    Meyers, published by Addison Wesley.</li>
 								</ul>
-												Minor updates


[SVN r7769]

											
										
										
											2000-09-23 02:06:56 +08:00
+								<ul>
 								  <li>Use the C++ Standard Library or other Boost libraries, but only when the
 								    benefits outweigh the costs.&nbsp; Do not use libraries other than the C++
 								    Standard Library or Boost. See <a href="library_reuse.htm">Library reuse</a>.</li>
 								</ul>
 								<ul>
 								  <li>Read <a href="imp_vars.htm">Implementation Variation</a> to see how to
 								    supply performance, platform, or other implementation variations.</li>
 								</ul>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<ul>
-												clarify naming conventions


[SVN r17662]

											
										
										
											2003-02-27 03:56:52 +08:00
+								  <li>Use the naming conventions of the C++ Standard Library (See
 								  <a href="#Naming">Naming conventions rationale</a>): <br>
 								&nbsp;<ul>
 								  <li>Names (except as noted below) should be all lowercase, with words
 								  separated by underscores.</li>
 								  <li>Acronyms should be treated as ordinary names (e.g. <code>xml_parser</code> instead of <code>XML_parser</code>).</li>
 								  <li>Template parameter names begin with an uppercase letter.</li>
 								  <li>Macro (gasp!) names all uppercase and begin with BOOST_.</li>
 								</ul>
 								  </li>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								</ul>
-												Minor changes, including add "Boost" to many page titles


[SVN r8985]

											
										
										
											2001-02-07 03:22:47 +08:00
+								<ul>
 								  <li>Choose meaningful names - explicit is better than implicit, and readability counts.
 								    There is a strong preference for clear and descriptive names, even if
 								    lengthy.</li>
 								</ul>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<ul>
 								  <li>Use exceptions to report errors where appropriate, and write code that is
 								    safe in the face of exceptions.</li>
 								</ul>
 								<ul>
 								  <li>Avoid exception-specifications. See <a href="#Exception-specification">exception-specification
 								    rationale</a>.</li>
 								</ul>
 								<ul>
-												Minor web page updates


[SVN r8810]

											
										
										
											2001-01-30 02:37:10 +08:00
+								  <li>Provide sample programs or confidence tests so potential users can see how
 								    to use your library.</li>
 								</ul>
 								<ul>
 								  <li>Provide a regression test program or programs which follow the <a href="test_policy.htm">Test
 								    Policies and Protocols</a>.</li>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								</ul>
 								<ul>
 								  <li>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:
 								    <ul>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								      <li>Use fixed-width fonts.&nbsp; See <a href="#code_fonts">fonts rationale</a>.</li>
-												Add tabs and JavaScript rationale


[SVN r15252]

											
										
										
											2002-09-10 22:13:01 +08:00
+								      <li>Use spaces rather than tabs. See <a href="#Tabs">tabs rationale</a>.</li>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								      <li>Limit line lengths to 80 characters.</li>
 								    </ul>
 								  </li>
 								</ul>
-												Minor updates


[SVN r7769]

											
										
										
											2000-09-23 02:06:56 +08:00
+								<ul>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								  <li>End all documentation files (HTML or otherwise) with a copyright message
 								  and a licensing message. See the <a href="#Copyright">end of this file</a> for
 								  an example of the preferred form.</li>
 								</ul>
 								<ul>
 								  <li>Begin all source files (including programs, headers, scripts, etc.) with:
-												Reflect license file renaming to accomodate more operating systems, and list discussions of exact copyright/license comments wording.


[SVN r20215]

											
										
										
											2003-09-30 08:59:29 +08:00
+								  <br>
 								&nbsp;<ul>
 								      <li>A comment line describing the contents of the file.<br>
 								&nbsp;</li>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								      <li>Comments describing copyright and licensing. The preferred form is:<br>
 								      <br>
-												Reflect license file renaming to accomodate more operating systems, and list discussions of exact copyright/license comments wording.


[SVN r20215]

											
										
										
											2003-09-30 08:59:29 +08:00
+								        <code>//&nbsp; Copyright Jane Programmer 2002. Use, modification and
 								      distribution is<br>
 								      //&nbsp; subject to the Boost Software License, Version 1.0. (See
 								      accompanying<br>
 								      //&nbsp; file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)<br>
 								      </code>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								        <br>
-												Reflect license file renaming to accomodate more operating systems, and list discussions of exact copyright/license comments wording.


[SVN r20215]

											
										
										
											2003-09-30 08:59:29 +08:00
+								      Please leave an empty line before and after the copyright and license
 								      comments.<br>
 								      <br>
 								      See <a href="license_info.html">license information page</a> for
 								      more information about the Boost Software License.<br>
 								&nbsp;</li>
 								      <li>A comment line referencing your library on the Boost web site. For
 								      example:<br>
-												Add /libs/lib-name to comment


[SVN r16684]

											
										
										
											2002-12-23 10:08:41 +08:00
+								      <br>
-												Reflect license file renaming to accomodate more operating systems, and list discussions of exact copyright/license comments wording.


[SVN r20215]

											
										
										
											2003-09-30 08:59:29 +08:00
+								        <code>//&nbsp; See http://www.boost.org/libs/foo for library home page.</code><br>
-												Add /libs/lib-name to comment


[SVN r16684]

											
										
										
											2002-12-23 10:08:41 +08:00
+								        <br>
 								      where <code>foo</code> 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.</li>
-												Minor updates


[SVN r7769]

											
										
										
											2000-09-23 02:06:56 +08:00
+								    </ul>
 								  </li>
 								</ul>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								<h3><a name="Directory_structure">Directory Structure</a> and Filenames</h3>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								<ul>
-												Tighten requirements on filenames, add review manager duties, reorganize a bit


[SVN r9977]

											
										
										
											2001-04-25 03:49:05 +08:00
+								  <li>File and directory names must contain only lowercase ASCII letters ,
 								    numbers, underscores, and a period.&nbsp; Leading character must be
 								    alphabetic. Maximum length 31. Only a single period is permitted.&nbsp;
 								    These requirements ensure file and directory names are relatively portable.</li>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								  <li>All libraries have at their highest level a primary directory named for
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								    the particular library. See <a href="#Naming<6E>_consistency">Naming consistency</a>. The primary directory may have sub-directories.</li>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								  <li>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).</li>
 								</ul>
 								<blockquote>
 								  <p><b>Boost standard sub-directory names</b></p>
 								  <table border="1" cellpadding="5">
 								    <tr>
 								      <td><b>Sub-directory</b></td>
 								      <td><b>Contents</b></td>
 								      <td><b>Required</b></td>
 								    </tr>
 								    <tr>
 								      <td><code>build</code></td>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								      <td>Library build files such as a Jamfile.</td>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								      <td>If any build files.</td>
 								    </tr>
 								    <tr>
 								      <td>doc</td>
 								      <td>Documentation (HTML) files.</td>
 								      <td>If several doc files.</td>
 								    </tr>
 								    <tr>
 								      <td><code>example</code></td>
 								      <td>Sample program files.</td>
 								      <td>If several sample files.</td>
 								    </tr>
 								    <tr>
 								      <td><code>src</code></td>
 								      <td>Source files which must be compiled to build the library.&nbsp;</td>
 								      <td>If any source files.</td>
 								    </tr>
 								    <tr>
 								      <td><code>test</code></td>
 								      <td>Regression or other test programs or scripts.</td>
 								      <td>If several test files.</td>
 								    </tr>
 								  </table>
 								</blockquote>
-												Add tabs and JavaScript rationale


[SVN r15252]

											
										
										
											2002-09-10 22:13:01 +08:00
+								<h4><a name="Redirection">Redirection</a></h4>
-												Clarify redirection, add rationale


[SVN r16623]

											
										
										
											2002-12-16 21:54:56 +08:00
+								<p>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 <i>http://www.boost.org/libs/lib-name</i> 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.</p>
 								<p>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:</p>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								<blockquote>
 								  <pre>&lt;html&gt;
 								&lt;head&gt;
 								&lt;meta http-equiv=&quot;refresh&quot; content=&quot;0; URL=doc/index.html&quot;&gt;
 								&lt;/head&gt;
 								&lt;body&gt;
 								Automatic redirection failed, please go to
 								&lt;a href=&quot;doc/index.html&quot;&gt;doc/index.html&lt;/a&gt;
 								&lt;/body&gt;
 								&lt;/html&gt;</pre>
 								</blockquote>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								<h3><a name="Naming<6E>_consistency">Naming consistency</a></h3>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								<p>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 which need their own header subdirectories and
 								namespaces.</p>
 								<p>Here is how it works. The library is given a name which describes the
 								contents of the library.&nbsp; Cryptic abbreviations are not acceptable.
 								Following the practice of the C++ Standard Library, names are usually singular
 								rather than plural.&nbsp; For example, a library dealing with file systems might
 								chose the name &quot;filesystem&quot;, but not &quot;filesystems&quot;, &quot;fs&quot; or &quot;nicecode&quot;.</p>
 								<ul>
 								  <li>The library's primary directory (in parent <i>boost-root/libs</i>) is
 								  given that same name.&nbsp; For example, <i>boost-root/libs/filesystem</i>.<br>
 								&nbsp;</li>
 								  <li>The library's primary header directory (in parent <i>boost-root/boost</i>)
 								  is given that same name. For example, <i>boost-root/boost/filesystem</i>.<br>
 								&nbsp;</li>
 								  <li>The library's primary namespace (in parent <i>::boost</i>) is given that
 								  same name. For example, <i>::boost::filesystem</i>.</li>
 								</ul>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								<h3><a name="Documentation">Documentation</a></h3>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p>Even the simplest library needs some documentation; the amount should be
 								proportional to the need.&nbsp; The documentation should assume the readers have
 								a basic knowledge of C++, but are not necessarily experts.</p>
 								<p>The format for documentation should be HTML, and should not require an
-												Add tabs and JavaScript rationale


[SVN r15252]

											
										
										
											2002-09-10 22:13:01 +08:00
+								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 <a href="#Redirection">
 								Redirection</a>.</p>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p>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 &quot;average&quot;
 								C++ programmer to use the library successfully?</p>
 								<p>Appropriate topics for documentation often include:
 								<ul>
 								  <li>General introduction to the library.</li>
 								  <li>Description of each class.</li>
 								  <li>Relationship between classes.</li>
-												Added links to the writing documentation pages.


[SVN r13199]

											
										
										
											2002-03-15 07:30:00 +08:00
+								  <li>For each function, as applicable, description, requirements (preconditions),
 								    effects, post-conditions, returns, and throws.</li>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  <li>Discussion of error detection and recovery strategy.</li>
 								  <li>How to use including description of typical uses.</li>
 								  <li>How to compile and link.</li>
 								  <li>How to test.</li>
 								  <li>Version or revision history.</li>
-												Added links to the writing documentation pages.


[SVN r13199]

											
										
										
											2002-03-15 07:30:00 +08:00
+								  <li>Rationale for design decisions.&nbsp; See <a href="#Rationale">Rationale
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								    rationale</a>.</li>
-												Added links to the writing documentation pages.


[SVN r13199]

											
										
										
											2002-03-15 07:30:00 +08:00
+								  <li>Acknowledgements.&nbsp; See <a href="#Acknowledgements">Acknowledgments
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								    rationale.</a></li>
 								</ul>
-												Added links to the writing documentation pages.


[SVN r13199]

											
										
										
											2002-03-15 07:30:00 +08:00
+								<p>If you need more help with how to write documentation you can check out the
 								  article on <a href="writingdoc/index.html">Writing Documentation for Boost</a>.</p>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								<h2><a name="Rationale">Rationale</a></h2>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p>Rationale for some of the requirements and guidelines follows.</p>
-.19.0 runup


[SVN r8446]

											
										
										
											2000-12-10 23:53:46 +08:00
+								<hr>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<h3><a name="Exception-specification">Exception-specification</a> rationale</h3>
 								<p>Exception specifications [ISO 15.4] are sometimes coded to indicate what
 								exceptions may be thrown, or because the programmer hopes they will improved
-												Add links to compatibility library


[SVN r9840]

											
										
										
											2001-04-19 23:04:01 +08:00
+								performance.&nbsp; But consider the following member from a smart pointer:</p>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<pre>    T&amp; operator*() const throw()  { return *ptr; }</pre>
 								<p>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.&nbsp; 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 &quot;dumb&quot; compiler, however, may make
 								all kinds of pessimizations.</p>
 								<p>For example, some compilers turn off inlining if there is an
 								exception-specification.&nbsp; Some compilers add try/catch blocks. Such
 								pessimizations can be a performance disaster which makes the code unusable in
 								practical applications.</p>
 								<p>Although initially appealing, an exception-specification tends to have
 								consequences that require <b>very</b> 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.</p>
 								<p>A non-inline function is the one place a &quot;throws nothing&quot;
 								exception-specification may have some benefit with some compilers.</p>
 								<hr>
 								<h3><a name="Naming">Naming</a> conventions rationale</h3>
 								<p>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:</p>
 								<ul>
 								  <li>Naming conventions are contentious, and although several are widely used,
-												Minor changes, including add "Boost" to many page titles


[SVN r8985]

											
										
										
											2001-02-07 03:22:47 +08:00
+								    no one style predominates.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>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
-												Minor changes, including add "Boost" to many page titles


[SVN r8985]

											
										
										
											2001-02-07 03:22:47 +08:00
+								    conventions.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								  <li>Once a library settles on a particular convention, a vast majority of
-												Minor changes, including add "Boost" to many page titles


[SVN r8985]

											
										
										
											2001-02-07 03:22:47 +08:00
+								    stakeholders want that style to be consistently used.
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								  </li>
 								</ul>
 								<hr>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								<h3>Source <a name="code_fonts">code fonts</a> rationale</h3>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p>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.</p>
 								<hr>
-												Add tabs and JavaScript rationale


[SVN r15252]

											
										
										
											2002-09-10 22:13:01 +08:00
+								<h3><a name="Tabs">Tabs</a> rationale</h3>
 								<p>Tabs are banned because of the practical problems caused by tabs in
 								multi-developer projects like Boost, rather than any dislike in principle. See
 								<a href="mailing_lists.htm#archive">mailing list archives</a>. 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 &quot;no tabs&quot;. Discussions concluded that Boost files should either all use
 								tabs, or all use spaces, and thus the decision to stick with spaces.</p>
 								<hr>
 								<h3>ECMAScript/<a name="JavaScript">JavaScript</a> rationale</h3>
 								<p>Before the 1.29.0 release, two Boost libraries added ECMAScript/JavaScript
 								documentation. Controversy followed (see <a href="mailing_lists.htm#archive">
 								mailing list archives</a>), and the developers were asked to remove the
 								ECMAScript/JavaScript. Reasons given for banning included:</p>
 								<ul>
 								  <li>Incompatible with some older browsers and some text based browsers.</li>
 								  <li>Makes printing docs pages difficult.</li>
 								  <li>Often results in really bad user interface design.</li>
 								  <li>&quot;It's just annoying in general.&quot;</li>
 								  <li>Would require Boost to test web pages for ECMAScript/JavaScript
 								  compliance.</li>
 								  <li>Makes docs maintenance by other than the original developer more
 								  difficult.</li>
 								</ul>
 								<hr>
-												fix invalid bookmarks


[SVN r16823]

											
										
										
											2003-01-09 21:03:37 +08:00
+								<h3><a name="Rationale_rationale">Rationale rationale</a></h3>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p>Rationale is defined as &quot;The fundamental reasons for something;
-												Add tabs and JavaScript rationale


[SVN r15252]

											
										
										
											2002-09-10 22:13:01 +08:00
+								basis&quot; by the American Heritage Dictionary.</p>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								<p>Beman Dawes comments:&nbsp; Failure to supply contemporaneous rationale for
 								design decisions is a major defect in many software projects. Lack of accurate
-												typo spotted by Gennaro Prota


[SVN r17565]

											
										
										
											2003-02-21 06:01:48 +08:00
+								rationale causes issues to be revisited endlessly, causes maintenance bugs when a
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
+								maintainer changes something without realizing it was done a certain way for
 								some purpose, and shortens the useful lifetime of software.</p>
 								<p>Rationale is fairly easy to provide at the time decisions are made, but very
 								hard to accurately recover even a short time later.</p>
 								<hr>
 								<h3><a name="Acknowledgements">Acknowledgements</a> rationale</h3>
 								<p>As a library matures, it almost always accumulates improvements suggested to
 								the authors by other boost members.&nbsp; It is a part of the culture of
 								boost.org to acknowledge such contributions, identifying the person making the
 								suggestion.&nbsp; Major contributions are usually acknowledged in the
 								documentation, while minor fixes are often mentioned in comments within the code
 								itself.</p>
 								<hr>
-												Add license links, copyright messages, plus changes to reflect new license


[SVN r19682]

											
										
										
											2003-08-19 00:40:06 +08:00
+								<p>Revised
-												Update copyright and license info


[SVN r20242]

											
										
										
											2003-10-02 22:42:46 +08:00
+								<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->02 October, 2003<!--webbot bot="Timestamp" endspan i-checksum="38549" --></p>
 								<p> <20> <a name="Copyright">Copyright</a> Beman Dawes 2003.</p>
 								<p> Use, modification, and distribution is subject to the Boost Software
 								License, Version 1.0. (See accompanying file <a href="../LICENSE_1_0.txt">
 								LICENSE_1_0.txt</a> or copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
 								www.boost.org/LICENSE_1_0.txt</a>)</p>
-												Initial HTML commit


[SVN r7640]

											
										
										
											2000-07-27 22:27:00 +08:00
 								</body>
-												Add TOC, primary directory index.htm redirection, and naming consistency sections


[SVN r14903]

											
										
										
											2002-08-16 03:41:01 +08:00
+								</html>