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