[Boost-commit] svn:boost r86710 - trunk/libs/geometry/doc

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]