mirror of
https://github.com/boostorg/more.git
synced 2024-12-26 23:30:29 +08:00
347 lines
16 KiB
HTML
347 lines
16 KiB
HTML
<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.
|
|
</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
|
|
"I just started to read this mailing list ..." 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. If a
|
|
portable implementation is not possible, non-portable constructions are
|
|
acceptable if reasonably easy to port to other environments.
|
|
</li>
|
|
<li>
|
|
<p align="left">There is no requirement that a library run on C++ compilers
|
|
which do not conform to the ISO standard.
|
|
</li>
|
|
<li>
|
|
<p align="left">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 <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. 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? "How to Copyright Software" 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. 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. 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, "Effective
|
|
C++" 2nd Edition, and "More Effective C++", 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. 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. 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. 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></h3>
|
|
<ul>
|
|
<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. </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. 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 "average"
|
|
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. See <a href="#Rationale">Rationale
|
|
rationale</a>.</li>
|
|
<li>Acknowledgements. 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. But consider the follow member from a smart pointer:</p>
|
|
<pre> T& 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. The function is completely
|
|
exposed to the compiler; indeed it is declared inline Therefore, a smart
|
|
compiler can easily deduce that the functions are incapable of throwing
|
|
exceptions, and make the same optimizations it would have made based on the
|
|
empty exception-specification. A "dumb" compiler, however, may make
|
|
all kinds of pessimizations.</p>
|
|
<p>For example, some compilers turn off inlining if there is an
|
|
exception-specification. Some compilers add try/catch blocks. Such
|
|
pessimizations can be a performance disaster which makes the code unusable in
|
|
practical applications.</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 "throws nothing"
|
|
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 "The fundamental reasons for something;
|
|
basis." by the American Heritage Dictionary.</p>
|
|
<p>Beman Dawes comments: Failure to supply contemporaneous rationale for
|
|
design decisions is a major defect in many software projects. Lack of accurate
|
|
rationale causes issues to 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. It is a part of the culture of
|
|
boost.org to acknowledge such contributions, identifying the person making the
|
|
suggestion. Major contributions are usually acknowledged in the
|
|
documentation, while minor fixes are often mentioned in comments within the code
|
|
itself.</p>
|
|
<hr>
|
|
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->06 February, 2001<!--webbot bot="Timestamp" endspan i-checksum="40406" --></p>
|
|
|
|
</body>
|
|
|
|
</html>
|