1                     Coding Standards for Marble
2                     ===========================
3
4
5This file contains the coding standards for Marble.  If you want to
6add or change code in Marble, you must follow these standards.
7
8
9Foundation
10----------
11
12The foundation for these standards is the kdelibs coding style.  It is
13described here: https://community.kde.org/Policies/Kdelibs_Coding_Style
14I suggest that you start by reading that document, it's not long.
15
16
17Recapitulation
18--------------
19
20Let's recapitulate a few key points from the kdelibs coding
21style. This is not the full standard, but just the most important
22points.
23
24 - 4 spaces indentation
25 - no tabs in the source code
26 - opening braces at end of line (except struct, class, functions and
27   namespaces)
28 - as little abbreviation in variable names as possible
29 - one variable declaration per line
30 - whitespace after control statements
31 - no space after pointer or reference ('*foo', not '* foo')
32 - no lines longer than 100 chars.
33
34That's a very short recapitulation of the above mentioned document.
35The full document contains lots of examples to show how it should be
36done.
37
38Class names and Variables
39-------------------------
40
41 - Class names should have the ("namespace") prefix "Marble" if
42
43    * they are parts of the Marble library that get exported.
44    * they resemble widgets or similar visually exposed items
45
46   The remaining part of the name should reflect the purpose of the
47   class and should be camel cased with the first letter being upper
48   cased.
49
50   All other classes should not have the "Marble" prefix.
51
52 - All header files should contain an include guard which prevents from
53   including a header file more than once. The include guard name consists
54   of the Marble namespace prefix (if the class is part of the Marble
55   namespace), the name of the class and an H. The name is in full upper case
56   and separated with an underscore.
57
58   Correct:
59      #ifndef MARBLE_ROUTINGWIDGET_H
60      #define MARBLE_ROUTINGWIDGET_H
61      ...
62      #endif // MARBLE_ROUTINGWIDGET_H
63
64   Wrong:
65      MARBLE_ROUTING_WIDGET_H
66      MARBLEROUTINGWIDGET_H
67      ROUTINGWIDGET_H
68      ROUTING_WIDGET_H
69
70 - camelCasing with the first letter being lower cased should be used
71   for methods and variables (e.g. myMethodName()). Full
72   upper cased names should be used for constants (e.g. RAD2DEG).
73
74Extensions
75----------
76
77The style defined above is not complete, so we have added the
78following item:
79
80
81Broken Lines in Expressions
82- - - - - - - - - - - - - -
83
84If an expression is so long that the line has to be broken, the break
85should occur *in front of* an operator, not *behind* it.
86
87Example:
88
89   var = very_long_sub_expression
90         + another_very_long_sub_expression;
91
92Another common case for this is logical expressions for if statements:
93
94    if (very_long_sub_expression
95        && another_very_long_sub_expression) {
96        doSomething();
97    }
98
99See also below for how to handle braces in this case.
100
101
102Special considerations for Marble
103---------------------------------
104
105Some things are only applicable for Marble.
106
107Abbreviations
108- - - - - - -
109
110Use the following abbreviations in variable names and comments:
111
112lon     longitude (not lng!)
113lat     latitude
114
115As parameters (and preferably in other places as well)
116longitude and latitude should appear in lon-lat order
117(not lat-lon!).
118