[Home]STLAlgorithmExtensions/Algorithm Standards

BOOST WIKI | STLAlgorithmExtensions | RecentChanges | Preferences | Page List | Links List

Difference (from prior major revision) (author diff)

Changed: 58c58,66
Organization</a> section.
Physical Organization</a> section.

No algorithm names should be hoisted into the global or boost namespace
unless there is a particularly compelling reason to do so. Users are free to
add using directives or using declarations to do that should they feel the
need. Adding a special header that includes all algorithms from a nested
namespace and hoists those algorithms into the outer namespace are acceptable,
but should be provided only as a convenience for users that want that behavior,
rather than as the preferred interface.

Changed: 62c70
must clearly imply the algorithm's behavior.
must clearly evoke the algorithm's behavior.

Documentation Outline

Detailed documentation for each algorithm should include the following elements:

///\brief A brief description of the algorithm.  This is the text that will
/// attract users to investigate the algorithm, so keep it short, clear, and
/// meaningful.
///
///\description A longer, complete yet succinct, description that includes
/// complexity details.  The long description can (and should) span many lines.
///
///\tparam Name describe a template parameter; name the iterator category or
/// concept that applies, if any.
///\tparam Name describe another template parameter
///
///\param Name describe a formal parameter's purpose and usage; if all are
/// intuitively obvious, there's no need to call them out
///\param Name describe another template parameter
///
///\pre describe a precondition (a condition that must hold upon entering the
/// function; which implies that satisfying the condition is the caller's
/// responsibility)
///\pre describe another precondition
///\post describe a postcondition (a condition that is guaranteed to hold upon
/// function return)
///\post describe another postcondition
///
///\code example code illustrating how to use the algorithm \endcode

Physical Organization

The current plans for organizing algorithms in Boost is to put most, if not all, algorithms in the Boost.Algorithm library. Algorithms will be put into appropriate subdirectories beneath boost/algorithm. The following subdirectories are currently recognized:

The String-algo library currently deviates from this notion of organizing algorithms as it contains sequence algorithms as well as string-specific algorithms.

Namespaces

All algorithm names should be namespace qualified. The namespace name to use should be that of the directory to which the algorithm belongs. See the Physical Organization section.

No algorithm names should be hoisted into the global or boost namespace unless there is a particularly compelling reason to do so. Users are free to add using directives or using declarations to do that should they feel the need. Adding a special header that includes all algorithms from a nested namespace and hoists those algorithms into the outer namespace are acceptable, but should be provided only as a convenience for users that want that behavior, rather than as the preferred interface.

Naming Conventions

Algorithm names are important. They should not be burdensome to type, but they must clearly evoke the algorithm's behavior.

Common Names

When there are established names for a particular behavior, don't invent new names. Even if you dislike the extant name, you and others have learned what it means and can associate that name with the behavior of that sort of algorithm.

Suffixes

The C++ Standard provides precedence for several suffixes that new algorithms should follow. As the need arises, other suffixes may be added to this list:

The prefixes may be combined in the following order: name[_copy][_n][_if].

Range Interfaces

All algorithms should include both an iterator interface and a range-based interface. Whether the range version should return an iterator or a range depends upon the algorithm. Returning a range permits chaining range-based algorithms, but returning an iterator may be more useful or more consistent with the iterator version.


BOOST WIKI | STLAlgorithmExtensions | RecentChanges | Preferences | Page List | Links List
Edit text of this page | View other revisions
Last edited May 12, 2008 11:37 am (diff)
Search:
Disclaimer: This site not officially maintained by Boost Developers