Subject: [Boost-commit] svn:boost r86710 - trunk/libs/geometry/doc
From: mateusz_at_[hidden]
Date: 2013-11-15 12:31:07
Author: mloskot
Date: 2013-11-15 12:31:07 EST (Fri, 15 Nov 2013)
New Revision: 86710
URL: http://svn.boost.org/trac/boost/changeset/86710
Log:
[geometry] Add guidelines for developers and maintainers (not yet generated into docs). Content moved from http://trac.osgeo.org/ggl/wiki/Developer/Guidelines
Added:
trunk/libs/geometry/doc/guidelines.qbk (contents, props changed)
Added: trunk/libs/geometry/doc/guidelines.qbk
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ trunk/libs/geometry/doc/guidelines.qbk 2013-11-15 12:31:07 EST (Fri, 15 Nov 2013) (r86710)
@@ -0,0 +1,221 @@
+[/============================================================================
+ 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 preferered line length is 80 characters, with maximum length of 100.
+* 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 should be formatted
+ with one template parameter per line, all parameters 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;
+* Curly
+```
+* Braces enclosing block of code (if-else, loops) should be placed in separate lines
+```
+if (expr)
+{
+}
+```
+* Parantheses 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.
+
+[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
+* All template parameters are in the struct, so no member template functions there
+* 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 <Tag, Geometry>
+struct foo
+{
+};
+
+// Specialization for POINT
+template <typename Point>
+struct foo<point_tag, Point>
+ : detail::foo::foo_point<Point> {};
+
+// Specialization for polygon
+template <typename Polygon>
+struct foo<polygon_tag, Polygon>
+ : detail::foo::foo_polygon<Polygon> {};
+
+} // namespace dispatch
+
+template <typename Point>
+inline int foo(Point const& point)
+{
+ return dispatch<typename tag<Point>::type, 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]