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: http://techbase.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;

If you use emacs, you can make it auto-indent by adding parenthesis to
the expression like this:

   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.


Exceptions
----------

The Marble coding style has a couple of exceptions to the foundation.


Spaces and Parenthesis
- - - - - - - - - - -

Due to historic reasons, the coding style of Marble has one
exception to the kdelibs style.  That exception is that we use the Qt
way of using parenthesis, with a space inside both opening and closing
parenthesis.  For example

Correct:

   if ( width > 100 ) {
      setHeight( 200 );
   }


Wrong:

   if (width > 100) {
      setHeight(200);
   }


Braces After Multi-line Expressions
- - - - - - - - - - - - - - - - - -

When an 'if' or 'while' statement has a long logical expression, the
following braces should be put at the beginning of the next line to
increase readability.

Correct:

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

Wrong:

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

As you can see, it is somewhat difficult to spot where the expression
ends and the action part begins if you just look at the left side.


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!).

Settings for Your Editor
------------------------

emacs
- - -

If you are an emacs user, you can put the following lines in your
.emacs file.  Then these style guidelines will be followed almost
automatically:


;; Don't use tabs in indentation
(setq-default indent-tabs-mode nil)

;; Use 4 space indentation
(setq-default c-basic-offset 4)


kate
- -

Under "Settings -> Configure Kate" adjust following parameters:
 - Check "Insert spaces instead of tabulators" on "Editing" page
 - Set "Tab width" to 4 on "Editing" page
 - Set "Encoding" to "Unicode ( utf-8 )" on "Open/Save" page
 - Set "End of line" to "Unix" on "Open/Save" page


vim
- -

If you are a vim user, add the following to your ~/.vimrc file.

:set cindent
:set tabstop=4
:set shiftwidth=4
:set expandtab