User Tools

Site Tools


coding_guidelines

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
coding_guidelines [2019/05/16 03:19]
daschuer [Command line]
coding_guidelines [2019/06/19 07:11] (current)
haslersn [Pointer, Object lifetime/Ownership]
Line 15: Line 15:
 Since 2019-05-09 our code formatting rules are defined by the [[https://​github.com/​mixxxdj/​mixxx/​blob/​master/​.clang-format|.clang-format]] configuration file. It can be found in the project root directory and contains settings for [[https://​clang.llvm.org/​docs/​ClangFormat.html|ClangFormat]]. **Make use of it by auto-formatting new or modified code segments as soon as you need to touch it!** Since 2019-05-09 our code formatting rules are defined by the [[https://​github.com/​mixxxdj/​mixxx/​blob/​master/​.clang-format|.clang-format]] configuration file. It can be found in the project root directory and contains settings for [[https://​clang.llvm.org/​docs/​ClangFormat.html|ClangFormat]]. **Make use of it by auto-formatting new or modified code segments as soon as you need to touch it!**
  
-The following options are available for auto-formatting the code. +ClangFormat ​version >= 4.0 is required.
- +
-clang-format ​version >= 4.0 is required+
  
 On Ubuntu, you can install clang format via. On Ubuntu, you can install clang format via.
Line 474: Line 472:
     * ''​parented_ptr''​ for ownership by the QT object tree: e.g. ''​auto p = make_parented<​T>​(...)''​     * ''​parented_ptr''​ for ownership by the QT object tree: e.g. ''​auto p = make_parented<​T>​(...)''​
  
-  * Pass raw pointer ''​T*''​ if no ownership is transfered. A function which receives a raw pointer should not hold onto the pointer ​outside the scope of the function (e.g. by storing it in a member variable). An exception is the parent pointer passed into the constructor of a ''​QObject''​ and internally stored as a non owning reference. Do not pass smart pointers by reference. ​+  * Pass reference ''​const T&''​ or ''​T&''​ if no ownership is transfered. ​Pass raw pointer ​''​const T*''​ or ''​T*''​ if no ownership is transfered ​and ''​nullptr''​ is a valid argument value. A function which receives a reference or raw pointer should not hold onto it outside the scope of the function (e.g. by storing it in a member variable). An exception is the parent pointer passed into the constructor of a ''​QObject''​ and internally stored as a non owning reference
 + 
 +  * Pass smart pointers by value if ownership is transfered (''​std::​unique_ptr''​) or shared (''​std::​shared_ptr''​). Do not pass smart pointers by reference.
  
-  * ''​parented_ptr'' ​requires the parent ​to be passed into the constructor at the time of creation. If pointer that will eventually ​be managed by the QT object tree needs to be temporarily ​created ​without ​a parent, first create ​the object ''​p''​ with ''​std::​make_unique'',​ and then later create a new variable using ''​parented_ptr(p.release())'' ​once the underlying object gets a parent.+  * Use ''​make_parented''​ to create objects derived from ''​QObject''​ that will be assigned to parent (and will therefore ​be managed by the Qt object tree). The created ​object must get a parent ​before ​the ''​parented_ptr'' ​is destructedExample:
  
-  ​Never store a ''​parented_ptr''​ in an object that outlives the parent. If the lifetime of the child relative to the parent ​is not clear then store the output of ''​parented_ptr::​toWeakRef()''​ instead.+    auto pBrowseButton = make_parented<​QPushButton>​(tr("​Browse"​));​ 
 +    // *pBrowseButton ​is not assigned to a parent yet 
 +    pLayout->​addWidget(pBrowseButton)
 +    // Now *pLayout is the parent
  
-  * Any exceptions ​to these guidelines ​must be clearly documented inline ​in the code+  * The destructor of ''​parented_ptr''​ asserts that the pointed-to object actually has a parent. This ensures that the pointed-to object isn't leaked. A consequence is that **a ''​parented_ptr'' ​must never dangle**. Never store a ''​parented_ptr'' ​in an object that outlives the parent. This is most easily done by storing the ''​parented_ptr''​ inside exact the parent. If the lifetime of the pointer relative to the parent is not clear then store the output of ''​parented_ptr::​toWeakRef()''​ instead of a ''​parented_ptr''​.
  
 +  * Any exceptions to these guidelines must be clearly documented inline in the code.
  
 ===== Assertions ===== ===== Assertions =====
Line 518: Line 522:
  
  
-===== C++11 =====+===== C++14 =====
  
-As of the Mixxx 2.release, Mixxx is switching to C++11. We are taking a conservative approach to adopting C++11 features and whitelisting them one by one. If a C++11 feature you would like to use is not listed here, please email mixxx-devel to make a case for it and we will consider whitelisting it.+As of the Mixxx 2.release, Mixxx is switching to C++14. We are taking a conservative approach to adopting C++11/14 features and whitelisting them one by one. If a C++11/14 feature you would like to use is not listed here, please email mixxx-devel to make a case for it and we will consider whitelisting it.
  
 We are limited to what is supported across our 3 supported compilers: We are limited to what is supported across our 3 supported compilers:
-  * [[http://​clang.llvm.org/​cxx_status.html|Clang 3.3]] +  * [[http://​clang.llvm.org/​cxx_status.html|Clang ​>= 3.4]] 
-  * [[https://​gcc.gnu.org/​projects/​cxx0x.html|GCC ​4.8]] +  * [[https://​gcc.gnu.org/​projects/​cxx0x.html|GCC ​>= 5.4 (Ubuntu Xenial)]] 
-  * [[https://​msdn.microsoft.com/​en-us/​library/​hh567368.aspx|Microsoft Visual Studio ​2015 Update 3]]+  * [[https://​msdn.microsoft.com/​en-us/​library/​hh567368.aspx|Microsoft Visual Studio ​2017 (_MSC_VER >= 1910)]]
  
 In general, Microsoft Visual Studio is the one that prevents us from using features. In general, Microsoft Visual Studio is the one that prevents us from using features.
coding_guidelines.1557991196.txt.gz · Last modified: 2019/05/16 03:19 by daschuer