123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232 |
- [/============================================================================
- Boost.Geometry (aka GGL, Generic Geometry Library)
- Copyright (c) 2007-2012 Barend Gehrels, Amsterdam, the Netherlands.
- Copyright (c) 2008-2012 Bruno Lalande, Paris, France.
- Copyright (c) 2009-2013 Mateusz Loskot, London, UK.
- Use, modification and distribution is subject to the Boost Software License,
- Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt)
- =============================================================================/]
- [section:guidelines Guidelines for developers]
- This library is maintained by several developers, and in order it to have
- a consistent design, look and feel, a few guidelines need to be followed.
- Rules of [@boost:/development/requirements.html Boost Library Requirements and Guidelines]
- and [@boost:/development/header.html Boost Header Policy] always have highest authority.
- Generally, prefer style of modern C++, conventions as used in latest C++ standard
- document and C++ Standard Library. Boost.Spirit is a good example of
- how to write and format high quality C++ code.
- Some guidelines specific to Boost.Geometry library are outlined below.
- [heading Code structure]
- * Every file shall have header with copyright and license information.
- * Do not put any history or revision information in comments in source files.
- Log it with VCS used in the Boost project.
- * Every header shall have `#include` guard based on header path and file name:
- ``
- #ifndef BOOST_GEOMETRY_<DIR1>_<DIR2>_<FILE>_HPP
- #define BOOST_GEOMETRY_<DIR1>_<DIR2>_<FILE>_HPP
- ...
- #endif // BOOST_GEOMETRY_<DIR1>_<DIR2>_<FILE>_HPP
- ``
- * `#include` directives shall be ordered according the most authoritative header:
- * C Standard Library (using C++ library names, i.e. `<cstdlib>`)
- * C++ Standard Library
- * Boost C++ Libraries
- * Boost.Geometry headers
- * Other 3rd-party headers (only if applicable! in some samples only)
- * Header within these sections should be ordered alphabetically, especially if there are many of them included.
- * Namespaces don't increase the level of indentation.
- In all other cases braces increase the level of indentation.
- ``
- namespace boost { namespace geometry
- {
- namespace mynewspace
- {
- template <typename Point>
- struct my_new_model
- {
- typedef point_type;
- }
- } // namespace mynewspace
- }} // namespace boost::geometry
- ``
- * Namespace closing brace should have comment with the namespace name.
- * All non-public headers should be placed into `boost/geometry/detail` or
- `boost/geometry/*/detail` directory, depending on component level.
- * All non-public names should reside in the `boost::geometry::detail` or
- `boost::geometry::*::detail` namespace, depending on component level.
- * All traits should be placed in dedicated `boost::geometry::traits` or
- `boost::geometry::*::traits` namespace
- * All tag dispatching routines should be placed in dedicated
- `boost::geometry::*::dispatch` namespace.
- * Access specifiers for class members shall be orderd as public first, then protected and private at the bottom.
- The public members define class interface, thus they are of the highest interested for users, so show them first.
- * Exceptions to this rule are allowed for typedef aliases required to be defined first.
- [heading Code formatting and indentation]
- * The code is indented with spaces, 4 spaces per tab.
- * The preferred line length is 80 characters, with maximum length of 100.
- * The limit is relaxed for very long string literals (e.g. Well-Known Text with data used in tests and examples).
- * Member/base initialization list for constructors on the same line,
- if it's small (1-2 members) or 1 member/base per line with leading comma on the left:
- ```
- struct T
- {
- T(int a, int b)
- : a(a)
- , b(b)
- {}
- int a;
- int b;
- };
- ```
- * Template declaration with long template parameter list shall be formatted
- with one template parameter per line, all parameters indented,
- but `<` and `>` brackets not indented:
- ```
- template
- <
- typename T,
- typename P,
- typename C = std::vector<Point>
- >
- struct polygon
- {
- typedef typename boost::remove_const
- <
- typename traits::point_type<T>::type
- >::type type
- };
- ```
- * References and pointers should be formatted emphasizing type, not syntax:
- ```
- T const& t;
- T* t;
- T* const t;
- T const* t;
- T const* const t;
- ```
- * Braces enclosing block of code (if-else, loops) should be placed in separate lines
- ```
- if (expr)
- {
- }
- ```
- * Parentheses around expressions should not be pre/post-fixed with spaces.
- [heading Naming conventions]
- * All names follow style of the C++ Standard, lowercase with words separated with underscore `_`,
- unless otherwise specified (see other rules).
- * Template parameters are named in CamelCase.
- * Concepts are named in CamelCase.
- * Name of a class data member shall start with `m_` prefix.
- The Boost sample header gives no prefix or suffix at all.
- However, the `m_` prefix is used in some (not many) Boost libraries as well (e.g. math/tools/remez).
- * All macro names shall be in upper-case, words separated with underscore `_`.
- * All macro names shall start with `BOOST_GEOMETRY_`.
- * All non-public macro names should start with `BOOST_GEOMETRY_DETAIL_` (not used often yet, if at all).
- * All public names should reside in the `boost::geometry` namespace.
- Nested namespaces are also possible.
- * Avoid cryptic names and abbreviations for elements used in wider context (e.g. types, functions).
- Short names are allowed if context of use is local, narrow and easily tracable
- For example, use of `it` for `iterator` in body of a loop in function:
- ```
- template <typename Range, typename Functor>
- static inline void apply(Range& range, Functor& f)
- {
- for (typename boost::range_iterator<Range>::type it = boost::begin(range);
- it != boost::end(range); ++it)
- {
- f(*it);
- }
- }
- ```
- [heading C++ use conventions]
- * Keyword struct is preferred either for POD structures, or for classes used at compile-time
- like metafunctions, tags, traits, etc.
- * Keyword class is preferred for classes meant to produce actual objects, which have methods
- and an active role in the runtime functioning of the program.
- * In case of a template, prefer use of typename keyword over class.
- [heading Specialisations and dispatching conventions]
- * Algorithms are free inline functions, taking any geometry. Parameters are often one or two geometries
- * There might be an overload for a strategy. The strategy takes, a.o. care of coordinate systems
- * The free `inline` function forwards to a dispatch struct, specialized for the geometry type (so for point, polygon, etc.)
- * They have an `static` (`inline`) function called apply
- * The dispatch struct calls, or is derived from, an struct implemented in namespace detail
- * There the same: a `struct` with a `static` (`inline`) function called apply
- * This way the implementation structs are building blocks, they can be reused
- * In fact they are reused often by the multi-versions of the algorithms
- ```
- namespace boost { namespace geometry
- {
- namespace detail { namespace foo
- {
- template <typename Point>
- struct foo_point
- {
- // template parameters here
- static inline int apply(Point const& p)
- {
- // do something here
- return 1;
- }
- };
- }} // namespace detail::foo
- namespace dispatch
- {
- template
- <
- Geometry,
- Tag = typename geometry::tag<Geometry>::type
- >
- struct foo
- {
- };
- // Specialization for POINT
- ...
- } // namespace dispatch
- template <typename Point>
- inline int foo(Point const& point)
- {
- return dispatch<Point>::apply(point);
- }
- }} // namespace boost::geometry
- ```
- [heading Contributing code]
- * Create a patch, open a ticket in the Boost Trac with your patch attached.
- * Alternatively, post your patch to the Boost.Geometry mailing list.
- * If you contribute a code, always try to provide a minimal test for it.
- [endsect]
|