From ee460e6eb47d22b0ba8a71212df146a912e14919 Mon Sep 17 00:00:00 2001 From: Jochen Topf Date: Tue, 23 Sep 2014 11:31:21 +0200 Subject: [PATCH] Various doc fixes. --- docs/contributing.markdown | 15 +++++++++++++-- docs/design.markdown | 8 ++++---- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/contributing.markdown b/docs/contributing.markdown index 49ba76dca..0ead90e82 100644 --- a/docs/contributing.markdown +++ b/docs/contributing.markdown @@ -17,6 +17,8 @@ Also read the design philosophy page for the motivations that lead to code decis Templates are good, within reason. We seek to use templates where possible for flexible code, but not in cases where functional patterns would be just as concise and clear. +Since version 3.0 we use C++11 which brings many advantages and makes the code easier to write and to read. + In general we use Boost, it makes more possible in C++. It is a big build time dependency (as in time to compile against and # of headers) but ultimately compiles to small object code and is very fast (particularly spirit). It also has no dependencies itself (it's really an extension to the C++ language) so requiring it is much easier than requiring a hard dependency that itself has other dependencies. This is a big reason that we prefer AGG to Cairo as our primary renderer. Also AGG produces the best visual output and strikes an excellent balance between speed and thread safety by using very lightweight objects. Cairo not so much. You will also notice that we don't use many of the standard geo libraries when we could. For instance we don't use GDAL, OGR, or GEOS anywhere in core, and only leverage them in optional plugins. We feel we can often write code that is faster and more thread safe than these libraries but that still does the job. If this ever changes we can adapt and start using these libraries or others as dependencies - nothing is nicer than standing on the shoulders of giants when it makes sense. @@ -102,20 +104,26 @@ which triggers locks (int)value; // no + #### Use const keyword after the type std::string const& variable_name // preferred, for consistency const std::string & variable_name // no + #### Pass built-in types by value, all others by const& void my_function(int double val); // if int, char, double, etc pass by value void my_function(std::string const& val); // if std::string or user type, pass by const& + #### Shared pointers should be created with [boost::make_shared](http://www.boost.org/doc/libs/1_47_0/libs/smart_ptr/make_shared.html) where possible +Since Mapnik 3.0 use std::make_shared. + + #### Use assignment operator for zero initialized numbers double num = 0; // please @@ -129,18 +137,21 @@ which triggers locks void foo (int a) // no + #### Separate arguments by a single space: void foo(int a, float b) // please void foo(int a,float b) // no + #### Space between operators: if (a == b) // please if(a==b) // no + #### Braces should always be used: if (!file) @@ -160,6 +171,7 @@ which triggers locks // more... } + #### Prefer `empty()` over `size() == 0` if container supports it This avoids implicit conversions to bool and reduces compiler warnings. @@ -171,8 +183,7 @@ This avoids implicit conversions to bool and reduces compiler warnings. ### Other C++ style resources -Many also follow the useful [google](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) which mostly fits our style. However, Google obviously has to maintain a lot of aging codebases. Mapnik can move faster, so we don't follow all -of those style recommendations. +Many also follow the useful [Google style guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml) which mostly fits our style. However, Google obviously has to maintain a lot of aging codebases. Mapnik can move faster, so we don't follow all of those style recommendations. ### Emacs helper diff --git a/docs/design.markdown b/docs/design.markdown index 4081ff8e4..42dddd237 100644 --- a/docs/design.markdown +++ b/docs/design.markdown @@ -1,19 +1,19 @@ # Design philosophy -Above all Mapnik is about making beautiful maps. This aim drives us to be constantly forward looking. Progress in technology and design are reshaping the art of the possible for maps. Mapnik joins the best ideas in high quality graphics with robust patterns and algorithms for spatial data access. The goal should be no less than enabling a new generation of map makers and gorgous maps. +Above all Mapnik is about making beautiful maps. This aim drives us to be constantly forward looking. Progress in technology and design are reshaping the art of the possible for maps. Mapnik joins the best ideas in high quality graphics with robust patterns and algorithms for spatial data access. The goal should be no less than enabling a new generation of map makers and gorgeous maps. Mapnik is a library. It is not a server - rather it's for writing servers. Or for writing desktop graphics engines to display maps. Or for visualizing new galaxies - its up to you. If you have an inclination for scripting and something to render in real world or celestial coordinates, Mapnik is for you. Mapnik is not a full solution, or even half a solution. At its best, Mapnik is a drawing api that provides the right tools for the developer to make sense of, and art from, geodata. But Mapnik is not just about drawing on a canvas. Beautiful maps can also be interactive maps and Mapnik aims to provide very flexible, custom access to geo features both in its C++ api and in binding languages. MetaWriters and the Grid renderer are two recent advances that enable highly interactive feature display in mapping applications using JSON serialized features, but more will come. -Mapnik core is simple set of objects providing structures for features and the ability to query, filter, cache, and render them. This design can be lightweight, flexible, and high performance because the core library does have to worry about where data comes from or where it goes after rendering. Datasources are separate plugin libraries loaded at runtime that, when called, provide feature arrays. The core classes make no assumptions about map size, format, or projection. The core is designed to make writing a high performance tile server, that renders on-demand and uses multi-threaded or multi-process concurrency, as easy as possible. +Mapnik core is a simple set of objects providing structures for features and the ability to query, filter, cache, and render them. This design can be lightweight, flexible, and high performance because the core library does not have to worry about where data comes from or where it goes after rendering. Datasources are separate plugin libraries loaded at runtime that, when called, provide feature arrays. The core classes make no assumptions about map size, format, or projection. The core is designed to make writing a high performance tile server, that renders on-demand and uses multi-threaded or multi-process concurrency, as easy as possible. Chasing beauty and speed, as technology advances, requires experimentation and a frequent stream of new ideas. To write fast and creative code we strive to avoid hard dependencies on older libraries or libraries that attempt to do too much at the cost of performance. At the same time, to be able to maintain ambitious goals we cannot write boilerplate code or attempt to write robust code for domains outside of mapping and graphics. As such we rely as much as possible on the Boost libraries. -Mapnik is cross platform because the C++ language and the Boost makes this feasible +Mapnik is cross platform because the C++ language and Boost makes this feasible enough it would be a shame not to be. But our development target is the latest -release of linux, particularly server based distributions, and many Mapnik developers +release of Linux, particularly server based distributions, and many Mapnik developers use OSX as a development environment. If you are having fun using Mapnik, stick with it. But, Mapnik is not always the right tool, of course. If you have small sets of data (MB's), try just rendering it in a web browser client using a javascript mapping api. Or if you need to set up an array of OGC Web services, use GeoServer. Lastly, if you are looking for a full solution for web cartography, use TileMill.