CODING

                     Coding Standards for Marble
                     ===========================


This file contains the coding standards for Marble.  If you want to
add or change code in Marble, you must follow these standards.


Foundation
----------

The foundation for these standards is the kdelibs coding style.  It is
described here: https://community.kde.org/Policies/Kdelibs_Coding_Style
I suggest that you start by reading that document, it's not long.


Recapitulation
--------------

Let's recapitulate a few key points from the kdelibs coding
style. This is not the full standard, but just the most important
points.

 - 4 spaces indentation
 - no tabs in the source code
 - opening braces at end of line (except struct, class, functions and
   namespaces)
 - as little abbreviation in variable names as possible
 - one variable declaration per line
 - whitespace after control statements
 - no space after pointer or reference ('*foo', not '* foo')
 - no lines longer than 100 chars.

That's a very short recapitulation of the above mentioned document.
The full document contains lots of examples to show how it should be
done.

Class names and Variables
-------------------------

 - Class names should have the ("namespace") prefix "Marble" if

    * they are parts of the Marble library that get exported.
    * they resemble widgets or similar visually exposed items

   The remaining part of the name should reflect the purpose of the 
   class and should be camel cased with the first letter being upper 
   cased.

   All other classes should not have the "Marble" prefix. 

 - All header files should contain an include guard which prevents from
   including a header file more than once. The include guard name consists
   of the Marble namespace prefix (if the class is part of the Marble 
   namespace), the name of the class and an H. The name is in full upper case
   and separated with an underscore.

   Correct:
      #ifndef MARBLE_ROUTINGWIDGET_H
      #define MARBLE_ROUTINGWIDGET_H
      ...
      #endif // MARBLE_ROUTINGWIDGET_H

   Wrong:
      MARBLE_ROUTING_WIDGET_H
      MARBLEROUTINGWIDGET_H
      ROUTINGWIDGET_H
      ROUTING_WIDGET_H

 - camelCasing with the first letter being lower cased should be used 
   for methods and variables (e.g. myMethodName()). Full 
   upper cased names should be used for constants (e.g. RAD2DEG).

Extensions
----------

The style defined above is not complete, so we have added the
following item:


Broken Lines in Expressions
- - - - - - - - - - - - - -

If an expression is so long that the line has to be broken, the break
should occur *in front of* an operator, not *behind* it.

Example:

   var = very_long_sub_expression
         + another_very_long_sub_expression;

Another common case for this is logical expressions for if statements:

    if (very_long_sub_expression
        && another_very_long_sub_expression) {
        doSomething();
    }

See also below for how to handle braces in this case.


Special considerations for Marble
---------------------------------

Some things are only applicable for Marble.

Abbreviations
- - - - - - -

Use the following abbreviations in variable names and comments:

lon     longitude (not lng!)
lat     latitude

As parameters (and preferably in other places as well) 
longitude and latitude should appear in lon-lat order
(not lat-lon!).


Dependencies
------------

Marble has a policy to be buildable using only recent versions of Qt and cmake.
I.e. to compile Marble with its basic functionality (library or app) no other dependencies are required.

However, certain features may only be enabled if additional optional dependencies are available.