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