Skip to content
This repository
tree: 9bace0f258
Fetching contributors…

Cannot retrieve contributors at this time

file 105 lines (69 sloc) 3.259 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105

Notes for Developers
====================

(Read this if you want to contribute to Osmium.)


Versioning
==========

Osmium is currently considered in beta and doesn't use versioning yet. Proper
versions will be introduced as soon as it is somewhat stable.


Namespace
=========

All Osmium code must be in the "Osmium" namespace or one of its sub-namespaces.


Include-Only
============

Osmium is a include-only library. You can't compile the library itself. There
is no libosmium.

One drawback ist that you can't have static data in classes, because there
is no place to put this data.


Coding Conventions
==================

These coding conventions have been changing over time and some code is still
different.

* Class names begin with uppercase chars and use CamelCase.
* Macros (and only macros) are all uppercase.
* Variables, attributes, and function names are lowercase with
  underscores_between_words.
* Class attribute names start with "m_" (member).
* Template parameters are single uppercase letters or start with uppercase "T"
  and use CamelCase.
* Typedefs have names_like_this_t which end in "_t".
* Macros should only be used for controlling which parts of the code should be
  included when compiling.
* Use descriptive_variable_names, exceptions are well-established conventions
  like "i" for a loop variable. Iterators are usually called "it".
* Declare variables where they are first used (C++ style), not at the beginning
  of a function (old C style).
* Names from external namespaces (even "std") are always mentioned explicitly.
  Do not use "using". The one exception are smart pointers and related functions.
  Include <osmium/smart_ptr.hpp> and use the functions without namespace.

Use "make indent" in the toplevel directory to fix indentation. It calls
"astyle" with the right parameters. This program is in the "astyle" Debian
package.


Debugging code
==============

Classes that need debugging should derive from Osmium::WithDebug. Debugging
code in those classes should be wrapped in

  if (debug && has_debug_level(LEVEL)) {
  }

Classes not derived from Osmium::WithDebug do not support debugging.

Debugging output (if it was requested) should go to std::cout.


Checking your code
==================

The Osmium makefiles use pretty draconian warning options for gcc.
This is good. Code should never produce any warnings, even with those
settings.

Call "make check" in the toplevel directory to check your code. It uses
cppcheck which finds some bugs that gcc doesn't. But take the result with
a grain of salt, it also sometimes produces wrong warnings.

Use "make check-includes" to compile all include files on their own to
check whether dependencies are all okay. This compiles with extra
draconian warnings, some of them you can ignore.


Testing
=======

There are a unit tests using the Boost Unit Test Framework in the 'test'
directory. Go there and type "./run_tests.sh" to compile and run the tests.
Many more tests are needed.


Documenting the code
====================

All namespaces, classes, functions, attributes, etc. should be documented.

Osmium uses the Doxygen (www.doxygen.org) source code documentation system.

Call "make doc" in the toplevel directory to generate the documentation.
Something went wrong with that request. Please try again.