Warning, /sdk/umbrello/CODING-STYLE is written in an unsupported language. File is not indexed.
0001 Umbrello coding style 0002 ===================== 0003 0004 A lot of successful software projects like Linux [1], boost [2], or 0005 Qt [3] have their own coding style guide. A coding style guide improves code 0006 quality, readability, and serves as a guideline for new developers. 0007 0008 Every file in Umbrello will sooner or later be ported by applying the guidelines 0009 described in this document. Every developer should at least consider the points 0010 made here. And sometimes, there may be a good reason to break a rule. 0011 0012 Some of the rules are already automatic tested by Krazy [6] every day. 0013 0014 0015 References: 0016 ----------- 0017 [ 1] http://lxr.linux.no/linux/Documentation/CodingStyle 0018 [ 2] http://www.boost.org/development/requirements.html 0019 [ 3] http://doc.trolltech.com/qq/qq13-apis.html and 0020 http://trolltech.com/developer/resources/notes/naming 0021 [ 4] http://techbase.kde.org/Policies/Kdelibs_Coding_Style 0022 [ 5] http://techbase.kde.org/Policies/Licensing_Policy 0023 [ 6] Krazy - http://www.englishbreakfastnetwork.org/ 0024 [ 7] http://techbase.kde.org/Policies/Library_Code_Policy 0025 [ 8] astyle - http://astyle.sourceforge.net/ 0026 [ 9] apidox - http://techbase.kde.org/Development/Tutorials/API_Documentation 0027 0028 0029 Formatting: 0030 ----------- 0031 * Indentation: 0032 1.) Do not use tabs [4]. 0033 2.) Indentations are 4 characters deep [4]. 0034 0035 * Whitespace: 0036 3.) Do not leave whitespaces at the end of lines. 0037 4.) Use blank lines to group statements [4]. 0038 5.) Use only one empty line to separate items [4]. 0039 6.) Use one space after each keyword [4]. 0040 Example: 0041 if( // wrong 0042 if ( // correct 0043 7.) Usage of whitespaces between an opening and closing parenthesis 0044 (e.g. if- and for-statments, function calls) is up to the developer. 0045 Example: 0046 if (i < 5) <-> if ( i < 5 ) 0047 calculateSalary(age, years); <-> calculateSalary( age, years ); 0048 8.) For pointers or references, use 0049 either a single space after '*' or '&', but not before (C++ style), 0050 Example: 0051 T* v and T& v 0052 Beware: 0053 char* i, j; // i is declared pointer to char, while j is declared char 0054 or a single space before '*' or '&', but not after (C style). 0055 Example: 0056 T *v and T &v 0057 9.) No space after a cast [4]. 0058 10.) Do not use spaces around '.' or '->', 0059 nor between unary operators and operands. 0060 0061 * Braces: 0062 11.) Function implementations, class, struct and namespace declarations 0063 always have the opening brace on the start of a line [4]. 0064 12.) For all other constructs (if, switch, for, ...), the left curly brace 0065 goes on the same line as the start of the statement [4]. 0066 13.) Use curly braces even when the body of a conditional statement contains 0067 only one line [4]. 0068 0069 * Statements: 0070 14.) Do not put multiple statements on a single line. 0071 0072 * Switch statements: 0073 15.) Case labels are on the same column as the switch [4]. 0074 0075 * Line breaks: 0076 16.) Try to keep lines shorter than 100 characters, inserting line breaks 0077 as necessary [4]. 0078 0079 * Pointers: 0080 17.) In C++, a null pointer is 0; not 0l, 0L or NULL. 0081 0082 0083 Variable declaration: 0084 --------------------- 0085 18.) Each variable declaration on a new line [4]. 0086 19.) Variables and functions start with a lowercase letter. 0087 20.) Classes always start with a capital letter. 0088 21.) Each new word in a name starts with a capital letter [4]. 0089 22.) Member variables start with "m_". 0090 23.) Do not use pseudo Hungarian style. 0091 Example: 0092 m_bSomeBoolean, m_pSomePointer // wrong 0093 m_someBoolean, m_somePointer // correct 0094 24.) Variables (objectName) in ui files start with "ui_". 0095 Rationale: 0096 This makes it possible to identify the source of the variable 0097 (defined in class or in ui file). 0098 25.) Use vertical alignment to ease scanning of declarations. 0099 Example: 0100 QString aStringToUse; 0101 int anInt; 0102 double aDoubleNumberToUse; 0103 26.) Use static const variables instead of defining integers or floats. 0104 Rationale: 0105 This provides type-safety. 0106 0107 0108 Casting: 0109 -------- 0110 27.) Use C++ style cast like static_cast, dynamic_cast instead of C style 0111 cast as it asserts the purpose of the cast. 0112 Also try to use Qt casts like qobject_cast, qgraphicsitem_cast in 0113 place of dynamic_cast wherever possible as the Qt style casts succeeds 0114 even across libraries. 0115 It doesn't mean dynamic casts shouldn't be used though. Use them 0116 wherever it is impossible to use Qt's cast. 0117 0118 0119 License: 0120 -------- 0121 28.) All source code and related data files must have the following 0122 license header from the first line on of the file (see also [5], 0123 checked by Krazy [6]). 0124 0125 /* 0126 Copyright <year> Umbrello UML Modeller Authors <umbrello-devel@kde.org> 0127 0128 This program is free software; you can redistribute it and/or 0129 modify it under the terms of the GNU General Public License as 0130 published by the Free Software Foundation; either version 2 of 0131 the License or (at your option) version 3 or any later version 0132 accepted by the membership of KDE e.V. (or its successor approved 0133 by the membership of KDE e.V.), which shall act as a proxy 0134 defined in Section 14 of version 3 of the license. 0135 0136 This program is distributed in the hope that it will be useful, 0137 but WITHOUT ANY WARRANTY; without even the implied warranty of 0138 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0139 GNU General Public License for more details. 0140 0141 You should have received a copy of the GNU General Public License 0142 along with this program. If not, see <http://www.gnu.org/licenses/>. 0143 */ 0144 0145 0146 Includes: 0147 --------- 0148 29.) Include own header first (checked by Krazy [6]). 0149 30.) Include Qt QClasses in angle brackets (checked by Krazy [6]). 0150 But do not add the QtModule like QtGui, because this will change 0151 in Qt5 and compilation will break. 0152 Example: 0153 #include <QtGui/QMenu> // wrong 0154 #include <QMenu> // correct 0155 31.) Include KDE KClasses in angle brackets (checked by Krazy [6]). 0156 Example: 0157 #include <kmessagebox.h> 0158 32.) Do not add a path to the include statement. 0159 Example: 0160 #include "../uml.h" // wrong 0161 #include "uml.h" // correct 0162 Rationale: 0163 Paths are set in the make files. Rearranging or moving files 0164 should not be followed by source code editing. 0165 33.) Header includes should be listed in the following order and grouped: 0166 - own header 0167 - Umbrello includes 0168 - KDE includes 0169 - Qt includes 0170 34.) The headers inside each group should be sorted. 0171 Rationale: 0172 For ease of locating them. 0173 Tip: 0174 Kate/KDevelop users can sort the headers automatically. 0175 Select the lines you want to sort, then 0176 Tools -> Filter Selection Through Command -> "sort". 0177 In vim the same can be achieved by marking the block, and then 0178 doing ":sort". 0179 In emacs, you can mark the block and then do "M-x sort-lines". 0180 35.) Includes in a header file should be kept to the absolute minimum, as 0181 to keep compile times low. This can be achieved by using forward 0182 declarations. 0183 Forward declarations work for pointers and const references. 0184 0185 0186 Include guards: 0187 --------------- 0188 36.) Include macro characters are all in uppercase letters. 0189 Example: 0190 #ifndef MyFileName_h // wrong 0191 #ifndef MY_FILE_NAME_H // correct 0192 37.) Do not use leading or trailing underscores on the include guard macro 0193 as they are reserved for compiler/libc use (checked by Krazy [6]?). 0194 Example: 0195 #ifndef _MY_FILE_NAME_H_ // wrong 0196 #ifndef MY_FILE_NAME_H // correct 0197 0198 0199 Doxygen comments: 0200 ----------------- 0201 38.) Every public item must have a doxygen comment. 0202 39.) Doxygen comments look like (see also [9]): 0203 /** 0204 * Here is the description... 0205 * @param ... ... 0206 * @return ... 0207 */ 0208 40.) The comments for methods should be written in the implementation file (cpp). 0209 The comments for the class should be written in the header file. 0210 Rational: 0211 The header files can be overviewed easier and read quicker. 0212 0213 0214 Header structure: 0215 ----------------- 0216 41.) According to policy, a C++ header file should contain only 1 publicly 0217 visible class. 0218 42.) Use the following layout: 0219 0220 <license> 0221 <include guard> 0222 <includes> 0223 0224 namespace 0225 { 0226 0227 /** 0228 * description 0229 */ 0230 class <name> : public <parent> 0231 { 0232 public: 0233 0234 protected: 0235 0236 private: 0237 0238 }; 0239 0240 } 0241 0242 0243 C++: 0244 ---- 0245 43.) "const correctness" should be preserved as much as possible. 0246 Make all getters const. 0247 44.) It might be a good idea to make the constructors explicit 0248 (checked by Krazy [6]). 0249 0250 0251 Metrics: 0252 -------- 0253 - loc = lines of code 0254 - Refactor classes, which have more than 1000 loc per class. 0255 - Refactor methods, which have more than 200 loc per method. 0256 0257 0258 Astyle: 0259 ------- 0260 You can use astyle to format one or several files with the following command: 0261 0262 astyle --indent=spaces=4 --brackets=linux \ 0263 --indent-labels --pad=oper --unpad=paren \ 0264 --one-line=keep-statements --convert-tabs \ 0265 --indent-preprocessor \ 0266 `find -type f -name '*.cpp'` `find -type f -name '*.h'` 0267 or 0268 astyle --indent=spaces=4 --brackets=linux \ 0269 --indent-labels --pad=oper --unpad=paren \ 0270 --one-line=keep-statements --convert-tabs \ 0271 --indent-preprocessor \ 0272 < Original > Beautified 0273 0274 This applies some of the rules in section 'Formatting'. 0275 0276 0277 Krazy: 0278 ------ 0279 The Perl script Krazy checks the code every day for some rules and lists 0280 the failed items on its web site (see [6]). 0281 0282