From f1e6f74c7d376f42a2852519a05c57368f374f12 Mon Sep 17 00:00:00 2001 From: arcan1s Date: Thu, 8 Oct 2015 01:08:59 +0300 Subject: [PATCH] * add CONTRIBUTING.md * add drop source ability for extsysmon --- CONTRIBUTING.md | 199 ++++++++++++++++++ .../plugin/awdataengineaggregator.cpp | 4 +- 2 files changed, 202 insertions(+), 1 deletion(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0b73f31 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,199 @@ +Code style +---------- + +The recommended code style is Qt one. See [this document](https://wiki.qt.io/Qt_Coding_Style) +for more details. Some additional detail see below. + +* Indent is only spaces. 4 spaces. +* It is highly recommended to name private variables with `m_` prefix (`m_foo`). +* Avoid to create a large methods. Exception: if method contains lambda functions. +* If some method is called only once, it is recommended to use lambda functions. + Exception is `Q_INVOKABLE` methods. +* STL containers are not recommended, use Qt one instead. +* In other hand Qt specific variables (`qint`, `qfloat`, etc) are not recommended. +* Do not repeat yourself ([DRY](https://en.wikipedia.org/wiki/Don't_repeat_yourself)). +* Headers declaration: + * Include only those headers which are strictly necessary inside headers. Use + forward class declaration instead. Exception is base class header declaration. + * In a`*.cpp` file header declaration should have the following order separated + by a new line in the alphabet order: + 1. Class header. + 2. KDE specific headers. + 3. Qt specific headers. + 4. Third party headers. + 5. Project headers. + * Any header should have [include guard](https://en.wikipedia.org/wiki/Include_guard) + named as `CLASSNAMECAPS_H` +* If any `#if` directive is used condition should be mentioned in `#endif`: + ``` + #if (FOO) + someCodeInside(); + #endif /* FOO */ + ``` +* `Q_PROPERTY` macro is allowed and recommended for QObject based classes. +* Qt macros (e.g. `signals`, `slots`, `Q_OBJECT`, etc) are allowed. +* Current project standard is **C++11**. +* Do not use C-like code: + * C-like style iteration if possible. Use `Q_FOREACH` (`foreach`) and + `std::for_each` instead if possible. It is also recommended to use iterators. + * C-like casts, use `const_cast`, `static_cast`, `dymanic_Cast` instead. Using + of `reinterpret_cast` is not recommended. It is highly recommended to use + `dynamic_Cast` with the exception catching. It is also possible to use + `qvariant_cast` if required. Exception is class constructors, e.g.: + ``` + char c = 'c'; + std::string s = "string"; + qDebug() << QString("some string") << QChar(c) << QString(s); + ``` + * C-like `NULL`, use `nullptr` instead. +* It is highly recommended to avoid implicit casts. +* Abstract classes (which has at least one pure virtual method) are allowed. +* Templates are allowed and recommended. Templates usually should be desribed + inside header not source code file. +* Hardcode is not recommended. But it is possible to use cmake variables to + configure some items during build time. +* Build should not require any addition system variable declaration/changing. +* Any line should not end with space. +* Do not hesitate move public methods to private one if possible. +* Do not hesitate use `const` modifier. In other hand `volatile` modifier is not + recommended. +* New lines rules: + * One line after license header. + * One line between header group declaration (see above). + * Two lines after header declaration and before declaration at the end of a + file. + * One line after class and types forward declaration in headers. + * One line before each method modifiers (`public`, `public slots`, etc). + * Two lines between methods inside source code (`*.cpp`). + * One line after `qCDebug()` information (see below). + * One line inside a method to improve code reading. +* Each destructor should be virtual. +* Class constructor should have default arguments. Use `QObject *parent` property + for QObject based classes. +* QObject based classes constructors should have explicit modifier. + +Comments +-------- + +Please do not hesitate to use comments inside source code (especially in non-obvious +blocks). Comments also may use the following keywords: + +* **TODO** - indicates that some new code should be implemented here later. Please + note that usually these methods should be implemented before the next release. +* **FIXME** - some dirty hacks and/or methods which should be done better. +* **HACK** - hacks inside code which requires to avoid some restrictions and/or + which adds additional non-obvious optimizations. + +Do not use dots at the end of the commend line. + +Development +----------- + +* Officially the latest libraries versions should be used. In addition it is + possible to add workarounds for all versions (usually by using preprocessor + directives). +* Build should not contain any warning. +* Try to minimize message in Release build with logging disabled. It is highly + recommended to fix KDE/Qt specific warning if possible +* Do not use dependency to KDE libraries if there are no any strictly necessary. + Exceptions are KNotification and KI18n libraries. +* It is highly recommended to use submodules for third party libraries if possible. +* The main branch is **development**. Changes in this branch may be merged to the + master one only if it is a 'stable' build. +* For experimental features development new branch `feature-foo` creation is allowed + and recommended. +* Experimental features should be added inside `BUILD_FUTURE` definition: + ``` + #ifdef BUILD_FUTURE + someTestFunctionInside(); + #endif /* BUILD_FUTURE */ + ``` +* Any project specific build variable should be mentioned inside `version.h` as + well. + +HIG +--- + +The recommended HIG is [KDE one](https://techbase.kde.org/Projects/Usability/HIG). + +Logging +------- + +For logging please use [QLoggingCategory](http://doc.qt.io/qt-5/qloggingcategory.html). +Available categories should be declared in `awdebug.*` files. The following log +level should be used: + +* **debug** (`qCDebug()`) - method arguments information, method calls notifications. +* **info** (`qCInfo()`) - additional information inside methods. +* **warning** (`qCWarning()`) - not critical information, which may be caused by + mistakes in configuration for example. +* **error** (`qCError()`) - an error which has been captured in runtime. All errors + should have own callback methods. +* **critical** (`qCCritical()`) - a critical error. After this error program will + be terminated. + +Testing +------- + +* Any changes should be tested by using `plasmawindowed` and `plasmashell` applications. + (It is also possible to use `plasmaengineexplorer` and `plasmoidviewer` in addition.) +* Any test should be performed on real (not Virtual Machine) system. +* Test builds should be: + 1. `-DCMAKE_BUILD_TYPE=Debug`. + 2. `-DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON`. + 3. `-DCMAKE_BUILD_TYPE=Release -DBUILD_TESTING=ON`. + 4. `-DCMAKE_BUILD_TYPE=Release`. +* It is recommended to create addition test if possible. +* Addition test functions should be declated and used only inside `BUILD_TESTING` + definition. + +Tools +----- + +* For QString concatenation use `QString::arg` method. +* Any source file should have license header: + ``` +/*************************************************************************** + * This file is part of awesome-widgets * + * * + * awesome-widgets is free software: you can redistribute it and/or * + * modify it under the terms of the GNU General Public License as * + * published by the Free Software Foundation, either version 3 of the * + * License, or (at your option) any later version. * + * * + * awesome-widgets is distributed in the hope that it will be useful, * + * but WITHOUT ANY WARRANTY; without even the implied warranty of * + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * + * GNU General Public License for more details. * + * * + * You should have received a copy of the GNU General Public License * + * along with awesome-widgets. If not, see http://www.gnu.org/licenses/ * + ***************************************************************************/ + ``` +* Recommended class constructor for QObject based classes: + ``` +FooClass::FooClass(QObject *parent, const QVariant var) + : QObject(parent), + m_var(var) +{ + qCDebug(LOG_AW); + // some code below if any +} + ``` +* Property usage: + ``` + Q_PROPERTY(bool prop READ prop WRITE setProp); +public: + bool prop() const + { + return m_prop; + }; + void setProp(const bool _prop) + { + // error checking if required + m_prop = _prop + } +private: + // declare with default value + bool m_prop = false; + ``` diff --git a/sources/awesome-widget/plugin/awdataengineaggregator.cpp b/sources/awesome-widget/plugin/awdataengineaggregator.cpp index a629328..ed04e08 100644 --- a/sources/awesome-widget/plugin/awdataengineaggregator.cpp +++ b/sources/awesome-widget/plugin/awdataengineaggregator.cpp @@ -93,8 +93,10 @@ void AWDataEngineAggregator::dropSource(const QString source) qCDebug(LOG_AW); qCDebug(LOG_AW) << "Source" << source; - // this method is only used for systemmonitor dataengine + // FIXME there is no possiblibity to check to which dataengine source connected + // we will try to disconnet it from systemmonitor and extsysmon m_dataEngines[QString("systemmonitor")]->disconnectSource(source, this); + m_dataEngines[QString("extsysmon")]->disconnectSource(source, this); }