|
|
Boost-Commit : |
From: daniel_james_at_[hidden]
Date: 2007-11-10 10:07:08
Author: danieljames
Date: 2007-11-10 10:07:08 EST (Sat, 10 Nov 2007)
New Revision: 40987
URL: http://svn.boost.org/trac/boost/changeset/40987
Log:
Add the library reuse guidelines. Fixes #1358.
Added:
website/public_html/beta/development/reuse.html (contents, props changed)
Text files modified:
website/public_html/beta/common/menu-development.html | 3 +++
1 files changed, 3 insertions(+), 0 deletions(-)
Modified: website/public_html/beta/common/menu-development.html
==============================================================================
--- website/public_html/beta/common/menu-development.html (original)
+++ website/public_html/beta/common/menu-development.html 2007-11-10 10:07:08 EST (Sat, 10 Nov 2007)
@@ -31,6 +31,9 @@
<li><a href="/development/header.html">Header policy <span class=
"link">></span></a></li>
+ <li><a href="/development/reuse.html">Library Reuse <span class=
+ "link">></span></a></li>
+
<li><a href="/development/int_const_guidelines.html">Coding
Guidelines for Integral Constant Expressions <span class=
"link">></span></a></li>
Added: website/public_html/beta/development/reuse.html
==============================================================================
--- (empty file)
+++ website/public_html/beta/development/reuse.html 2007-11-10 10:07:08 EST (Sat, 10 Nov 2007)
@@ -0,0 +1,119 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
+<head>
+ <title>Boost Library Reuse</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
+ <link rel="icon" href="/favicon.ico" type="image/ico" />
+ <link rel="stylesheet" type="text/css" href=
+ "/style/section-development.css" />
+ <!--[if IE]> <style type="text/css"> body { behavior: url(/style/csshover.htc); } </style> <![endif]-->
+</head>
+
+<body>
+ <div id="heading">
+ <!--#include virtual="/common/heading.html" -->
+ </div>
+
+ <div id="body">
+ <div id="body-inner">
+ <div id="content">
+ <div class="section" id="intro">
+ <div class="section-0">
+ <div class="section-title">
+ <h1>Boost Library reuse: cost versus benefit trade-offs</h1>
+ </div>
+
+ <div class="section-body">
+ <p>A Boost library <strong>should not</strong> use libraries
+ other than Boost or the C++ Standard Library.</p>
+
+ <p>A Boost library <strong>should</strong> use other Boost
+ Libraries or the C++ Standard Library, but only when the
+ benefits outweigh the costs.</p>
+
+ <p>The benefits of using components from other libraries may
+ include clearer, more understandable code, reduced development
+ and maintenance costs, and the assurance which comes from
+ reusing well-known and trusted building blocks.</p>
+
+ <p>The costs may include undesirable coupling between
+ components, and added compilation and runtime costs. If the
+ interface to the additional component is complex, using it may
+ make code less readable, and thus actually increase development
+ and maintenance costs.</p>
+
+ <p>Negative effects of coupling become obvious when one library
+ uses a second library which uses a third, and so on. The worst
+ form of coupling requires the user understand each of the
+ coupled libraries. Coupling may also reduce the portability of
+ a library - even in case when all used libraries are
+ self-sufficient (see example of questionable usage of
+ <iostream> library below).</p>
+
+ <p><strong>Example where another boost component should
+ certainly be used:</strong> boost::noncopyable (in <a href=
+ "../boost/utility.hpp">boost/utility.hpp</a>) has considerable
+ benefits; it simplifies code, improves readability, and signals
+ intent. Costs are low as coupling is limited; noncopyable
+ itself uses no other classes and its header includes only the
+ lightweight headers <boost/config.hpp> and
+ <cstddef>. There are no runtime costs at all. With costs
+ so low and benefits so high, other boost libraries should use
+ boost::noncopyable when the need arises except in exceptional
+ circumstances.</p>
+
+ <p><strong>Example where a standard library component might
+ possibly be used:</strong> Providing diagnostic output as a
+ debugging aid can be a nice feature for a library. Yet using
+ Standard Library <iostream> can involves a lot of
+ additional cost, particularly if <iostream> is unlikely
+ to be use elsewhere in the application. In certain GUI or
+ embedded applications, coupling to <iostream> would be a
+ disqualification. Consider redesign of the boost library in
+ question so that the user supplies the diagnostic output
+ mechanism.</p>
+
+ <p><strong>Example where another boost component should not be
+ used:</strong> The boost dir_it library has considerable
+ coupling and runtime costs, not to mention portability issues
+ for unsupported operating systems. While completely appropriate
+ when directory iteration is required, it would not be
+ reasonable for another boost library to use dir_it just to
+ check that a file is available before opening. C++ Standard
+ Library file open functionality does this at lower cost. Don't
+ use dir_it just for the sake of using a boost library.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div id="sidebar">
+ <!--#include virtual="/common/sidebar-common.html" -->
+ <!--#include virtual="/common/sidebar-development.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+ </div>
+
+ <div id="footer">
+ <div id="footer-left">
+ <div id="revised">
+ <p>Revised $Date: 2007-10-22 22:55:52 +0100 (Mon, 22 Oct 2007) $</p>
+ </div>
+
+ <div id="copyright">
+ <p>Copyright Beman Dawes 2000.</p>
+ </div><!--#include virtual="/common/footer-license.html" -->
+ </div>
+
+ <div id="footer-right">
+ <!--#include virtual="/common/footer-banners.html" -->
+ </div>
+
+ <div class="clear"></div>
+ </div>
+</body>
+</html>
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk