samien
/
boost
зеркало из https://github.com/boostorg/boost


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352
							<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 4.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">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">Requirements</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 to copy, use and modify the software for any use
    (commercial and non-commercial) for no fee.
  </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>
<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/index.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.org 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 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>.</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 lowercase/underscore <a href="#Naming">naming conventions</a> of
    the C++ standard library.&nbsp; Template parameter names begin with an
    uppercase letter. Macro (gasp!) names should be all uppercase and begin with
    BOOST_.</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.</li>
      <li>Limit line lengths to 80 characters.</li>
    </ul>
  </li>
</ul>
<ul>
  <li>Begin all source files with:
    <ul>
      <li>A comment line describing the contents of the file.</li>
      <li>Comments describing copyright and licensing.</li>
      <li>A comment line referencing the Boost home page in the form:<br>
        <code>// See http://www.boost.org for updates, documentation, and
        revision history.</code><br>
        [Including revision history in source files is no longer recommended;
        the publicly available CVS repository better serves that purpose.]</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. 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 make files or IDE project files.</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>
<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.</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>
<h2>Rationale</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="Rationale">Rationale</a> rationale</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 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 -->24 April, 2001<!--webbot bot="Timestamp" endspan i-checksum="29814" --></p>

</body>

</html>