diff --git a/src/doc/coding_style.dox b/src/doc/coding_style.dox index 111ebbf12..1a3a073d5 100644 --- a/src/doc/coding_style.dox +++ b/src/doc/coding_style.dox @@ -1,134 +1,134 @@ /**\page coding_style Coding Style The following rules are not used everywhere (yet), but are intended as guidelines for new code and eventually old code should be adapted as well. They apply to C++ and C code. The standards are C++11 and C99. \section files Files - Files use Unix-style line endings ('\\n'). - C++ source files use “.cpp” as extension, C source code use "*.c" and header files use “.h”. - The code is documented using Doxygen comments which are placed in the source files, not the header files. - Every file should be named exactly like the class inside and there should be only one class per file, with the exception of really short classes. Very short classes can be bundled in one file which then is named using all lower case letters. \section identifier Identifier names - Class names start with a capital letter and use CamelCase, acronyms in class names are use like normal words. Example: MySuperHtmlToPdfConverter - Function/method names start with a lower case letter and use CamelCase Example: doSomethingImportant() - Variable/object names start with a lower case letter and use CamelCase, underscores are used for special prefixes only. - Only private class member variables are prefixed with “m_” to distinguish them easily. d-pointer and UI-widgets are called d and ui, respectively, i.e. without prefix. - Property access methods use Qt style: property() and setProperty(), except for boolean properties (isVisible(), hasChanged()). Accessor functions (getter/setter) can be done using macros. - Avoid abbreviations, except for local counters and temporaries whose purpose is obvious. \section indent Indentation, spacing and line breaks - Tabs are used for indentation because they allow everyone to choose the indentation depth for him/herself. - Try to keep lines shorter than 100 characters, inserting line breaks as necessary and indent the following lines to improved readability. - included headers should be in order: own header, local header, Qt/KDE header, system header, extern header - Opening braces (‘{‘) are placed behind the statement and are preceded by a space. This also goes for function implementations, class, struct and namespace declarations, which are exceptions in other coding styles. Example: @code void MyClass::doSomething() { if (condition) { ... } ... } @endcode - Opening brackets (‘(‘) are preceded by a space in for/switch/if/while statements, but not for function calls. Example: @code if (condition) { doSomething(myData); ... } @endcode - For pointers or references, use a single space after ‘*’ or ‘&’ (i.e. specifier is bound to the data type not the name). Example: @code void doSomething(int* dataPointer, const QString& name); ... = static_cast(...) @endcode “public” and namespace enclosures are not indented. Example: @code class MyClass: public QObject { public: void doSomething(); @endcode “case” of switch is not indented. “default” should be present only if data type is not an enum. Example: @code switch (condition) { case 1: handleCaseOne(); break; case 2: { int i=0; ... break; } ... default: ... } @endcode - Each comma in a function call or semicolon in a for statement is followed by a space character; no space before the first and after the last argument. Example: @code for (int i = 0; i < 10; i++) { ... doSomething(arg1, arg2, arg3); } @endcode "else" (and "catch" if it is ever used) is put after the closing brace like this: "} else {" - Use as many brackets in conditions/math terms as you see fit for optimum readability. All operators ('=', '==', '<', '+', '-', '<<', etc.) and castings should always be surrounded by spaces. Examples: @code foo/2 + bar/4 + baz/3 for (int i = 0; i < bar+1; i++) var = (foo - 1) + (bar - 2) + (baz - 3) char *s = (char*) malloc(LENGTH * sizeof(char)); @endcode - enum and structs should be defined first in a class - parameter names in a method definition should only be used to explains the usage of the parameter - In SIGNAL() and SLOT() macros, use as little whitespace as possible. This gives a little speed up since Qt does not have to normalize the signal/slot name. \section constructs Usage of specific constructs * Use C++ casting (static_cast, const_cast, dynamic_cast) in C++ and qobject_cast in Qt classes since they include checks see https://en.wikibooks.org/wiki/C%2B%2B_Programming/Programming_Languages/C%2B%2B/Code/Statements/Variables/Type_Casting * In C++ use Qt container instead of STL container https://marcmutz.wordpress.com/effective-qt/containers/ * In C++ use range-based loops instead of foreach/Q_FOREACH https://www.kdab.com/goodbye-q_foreach/ * For integer data types int is preferred for small numbers and size_t for big, unsigned values. Use double as floating point type. -* The keyword 'auto' can be used in range-based loops but should be avoided else to maintain readability +* The 'auto' keyword should be used in range-based loops and for variables initialized by casting or with the 'new' operator but only for non-basic types. Do not omit '*' and '&' to keep readability. * use smart pointers unique_ptr when possible and shared_ptr otherwise. * Avoid const pass-by-value parameters in function declarations. Still make the parameter const in the same function's definition if it won't be modified. * Use the 'override' specifier when overriding virtual functions from the base class http://en.cppreference.com/w/cpp/language/override * Use braces to enclose a single statement only for readability * In C++ nullptr should be used instead of bug-prone NULL and 0. * #include <...> vs. #include "...": Include headers from external libraries using angle brackets (as in #include ) and headers from LabPlot/SciDAVis using double quotes (as in #include "core/AbstractAspect.h"). Rationale: Headers of external libraries are never in the same directory as the including file, so it makes sense to use the angle bracket form (which searches only in directories specified using -I). If you work with a build system that does not include the current source directory, or disable CMAKE_INCLUDE_CURRENT_DIR, then all angle-bracket-includes referencing LabPlot/SciDAVis headers will break. Excluding the current directory from -I dirs may be desirable one day when using a new library or a new version of a library containing a header file with the same name as one of our headers. * Use DEBUG() macro for debugging code when possible and QDEBUG() only for special Qt data types. DEBUG() works on all supported systems. @code QString string; DEBUG(" string : " << string.toStdString()); @endcode * Use Qt functions for user messages: qDebug(), qWarning(), qCritical(), qFatal(). Check conditions with Q_ASSERT(cond) or Q_ASSERT_X(cond, where, what) and pointers with Q_CHECK_PTR(ptr). * Import C header (from GSL etc.) with extern statement. We use "std::" prefix (C++11) and try to avoid C header like cmath, cfloat etc. by using corresponding C++ constructs (fabs() -> std::abs(), DBL_MAX -> std::numeric_limits::max(), round() -> qRound()). Example: @code extern "C" { #include } if (std::isnan(x)) { ... } @endcode \section links Links Apart from that, the following links are recommended as guidelines for the coding style: http://techbase.kde.org/index.php?title=Policies/Library_Code_Policy http://doc.trolltech.com/qq/qq13-apis.html http://techbase.kde.org/Policies/Kdelibs_Coding_Style */