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/02/16 07:39]
beenisss [Pointer, Object lifetime / Ownership]
coding_guidelines [2019/05/16 03:19] (current)
daschuer [Command line]
Line 9: Line 9:
 That being said, there are large chunks of Mixxx that are written in slightly differing styles (mainly variable naming conventions). In order to avoid this in the future, it's best for us to have some coding guidelines for developers to follow. ​ That being said, there are large chunks of Mixxx that are written in slightly differing styles (mainly variable naming conventions). In order to avoid this in the future, it's best for us to have some coding guidelines for developers to follow. ​
  
-**As you change a part of Mixxx, please update it to match this style guide. That way, eventually all of Mixxx will be written in this style. Do not send us patches that are purely cosmetic with respect to source changes -- this is a waste of time since it does not benefit users directly.** ​+**As you change a part of Mixxx, please update it to match this style guide and reformat it with ClangFormat. That way, eventually all of Mixxx will be written in this style. Do not send us patches that are purely cosmetic with respect to source changes -- this is a waste of time since it does not benefit users directly.** ​
  
-===== Tabs vs. Spaces ​=====+===== Code Formatting ​=====
  
-Mixxx'​s old developers more or less used the convention that **indents ​are 4 spaces**The consensus is that we should try to stick to this, if only for consistencyIf your code uses tabs, or does not use 4-space indent then you will be asked to change ​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!**
  
-===== Line Widths =====+The following options are available for auto-formatting the code.
  
-Please configure your editor to have a max column-width of 80-columnsWhile it is not a strict requirement,​ 80-column cleanliness makes it easy to tile multiple buffers of code across a laptop screen, which provides significant efficiency gains to developers. Use double indent (8-spaces) for broken lines or align with the opening "​("​ in the line above for hanging indents.+clang-format version >= 4.is required
  
-===== Auto-Formatter =====+On Ubuntu, you can install clang format via.
  
-We currently ​do not provide an auto-formatter ​or code-checker+<code bash> 
 +sudo apt-get install clang-format clang-format-4.0 
 +sudo update-alternatives --install /​usr/​bin/​clang-format clang-format /​usr/​bin/​clang-format-4.0 1000 
 +</​code>​ 
 + 
 + 
 + 
 + 
 + 
 +==== Command line ==== 
 + 
 +Use [[https://​raw.githubusercontent.com/​llvm-mirror/​clang/​master/​tools/​clang-format/​git-clang-format|git-clang-format]] to make sure your changes follow the mixxx style. 
 + 
 +[[https://​dx13.co.uk/​articles/​2015/​4/​3/​Setting-up-git-clang-format.html|Setting-up git-clang-format]] 
 + 
 +You can for example ​do this after each commit during development:​  
 +<code bash> 
 +git-clang-format HEAD^1 
 +git commit -a --amend 
 +</​code>​ 
 + 
 +or if the PR is already under review:  
 +<code bash> 
 +git-clang-format upstream/​master  
 +git commit -a -m"​apply git-clang-format changes"​ 
 +</​code>​ 
 +  
 + 
 +Apply //​clang-format//​ to individual source files (only permitted for new files): 
 + 
 +''​clang-format -i -style=file [<​file>​ ...]''​ 
 + 
 +//​clang-format//​ will pick up the //​.clang-format//​ file from the current or any parent directory of the source file(s). 
 + 
 +==== VisualStudio Code ==== 
 + 
 +Code formatting is available in [[https://​code.visualstudio.com|Visual Studio Code]]. Install the [[https://​marketplace.visualstudio.com/​items?​itemName=ms-vscode.cpptools|C/​C++ Extension]] and verify or update the following settings: 
 + 
 +  * //​**C_Cpp.formatting**//​ = //Default// (default) 
 +  * //​**C_Cpp.clang_format_style**//​ = //file// (default) 
 +  * //​**C_Cpp.clang_format_fallbackStyle**//​ = //​Google//​ 
 +  * //​**C_Cpp.clang_format_sortIncludes**//​ = //null// (default) 
 +  * //​**C_Cpp.clang_format_path**//​ = //null// (default) or //path to your clang-format executable//​ (optional) 
 + 
 +Don't enable auto-formatting on save, because this will add unnecessary noise to your pull request.  
 + 
 +  * //​**editor.formatOnSave**//​ = //false// 
 +  * //​**editor.formatOnType**//​ = //true// 
 + 
 +==== KDevelop ==== 
 +[[KDevelop]] has a [[https://​github.com/​KDE/​kdev-clang-tidy|clang-tidy plugin]]. 
 + 
 +==== Eclipse ====
  
 If you use Eclipse as IDE, the code style "​K&​R"​ works well with these tweaks ​ If you use Eclipse as IDE, the code style "​K&​R"​ works well with these tweaks ​
Line 27: Line 79:
   * new lines = before colon in constructor initializer list   * new lines = before colon in constructor initializer list
 Please note that there are still some exceptions, so do not auto-format a whole file. Please note that there are still some exceptions, so do not auto-format a whole file.
 +
 +In addition you can install [[https://​marketplace.eclipse.org/​content/​cppstyle]] to use clang-format from the GUI 
 +
 +===== Tabs vs. Spaces =====
 +
 +Mixxx'​s old developers more or less used the convention that **indents are 4 spaces**. The consensus is that we should try to stick to this, if only for consistency. If your code uses tabs, or does not use 4-space indent then you will be asked to change it.
 +
 +===== Line Widths =====
 +
 +Please configure your editor to have a max column-width of 80-columns. While it is not a strict requirement,​ 80-column cleanliness makes it easy to tile multiple buffers of code across a laptop screen, which provides significant efficiency gains to developers. Use double indent (8-spaces) for broken lines or align with the opening "​("​ in the line above for hanging indents.
 +
 +
  
 ====== C++ Style Guide ====== ====== C++ Style Guide ======
Line 123: Line 187:
 bool myFunction();​ bool myFunction();​
  
- // namespace mixxx +} // namespace mixxx
-// ^ Note two spaces after the closing brace.+
 </​code>​ </​code>​
  
Line 140: Line 203:
 // Put file-local helper functions and constants here. // Put file-local helper functions and constants here.
 bool myHelper() { bool myHelper() {
-  ​return true;+    ​return true;
 } }
  
- // namespace ​ +} // namespace ​
-// ^ Note two spaces after the closing brace.+
  
 // Put class implementations,​ functions, and constants ​ // Put class implementations,​ functions, and constants ​
 // that are meant to be used by other parts of Mixxx here. // that are meant to be used by other parts of Mixxx here.
-MyClass::​MyClass() : m_helper(myHelper()) {+MyClass::​MyClass():​ m_helper(myHelper()) {
 } }
  
 bool myFunction() { bool myFunction() {
-  ​return myHelper();+    ​return myHelper();
 } }
  
- // namespace mixxx +} // namespace mixxx
-// ^ Note two spaces after the closing brace.+
 </​code>​ </​code>​
  
Line 219: Line 280:
 ===== Comments ===== ===== Comments =====
  
-Use C++-style comments only. Do not use C-style comments or Java-syle comments. ​Comments should be complete, descriptive sentences in the present tense. If a comment is a warning or something that might need to be re-evaluated in the future, date the comment with the current month and year, along with your username+Comments should be complete, descriptive sentences in the present tense. If a comment is a warning or something that might need to be re-evaluated in the future, date the comment with the current month and year, along with your user name.
  
 **Good:** **Good:**
Line 227: Line 288:
 </​code>​ </​code>​
  
-Plain-text comments ​should be separated from the comment symbol by a single space. ​Commented-out code should have no space between the comment symbol and the code:+Prefer to use C++-style comments. All trailing line comments start with a single space after the separator.
  
-**Good:** +Avoid to use C-style comments or Java-style multi-line comments.
-<code cpp-qt> +
-// Textual comment +
-//if (thisSectionIsDeprecated) { +
-//    // Do something crufty +
-//} +
-</​code>​+
  
 **Bad:** **Bad:**
 <code cpp-qt> <code cpp-qt>
-//​Textual ​comment +/
-// if (thisSectionIsDeprecated+ * Java-style ​comment 
-//     // Do something crufty + * 
-// }+thisCommentIsReallyVerboseFactoryMethodInjectorObserver() 
 +/* C-style comment -- avoid because you can't nest them */
 </​code>​ </​code>​
- 
  
 Avoid comments that do not add more information than the words contained in the statement that follows them. Instead, write a descriptive summary of what the following lines accomplish. Avoid comments that do not add more information than the words contained in the statement that follows them. Instead, write a descriptive summary of what the following lines accomplish.
Line 254: Line 309:
 </​code>​ </​code>​
  
-**Bad:** +Avoid to comment out code unless a preceding textual ​comment ​explains the exact purpose of the following lines and why this code needs to be preserved as a comment. Commented out debugging statements without an additional description are acceptable if the intend is obvious.
-<code cpp-qt>​ +
-/* +
- * Java-style ​comment +
- */  +
-thisCommentIsReallyVerboseFactoryMethodInjectorObserver() +
-/* C-style comment -- avoid because you can't nest them */ +
-</code+
 ==== TODO's ==== ==== TODO's ====
  
Line 379: Line 426:
     // bindWidget gives the Library a chance to insert logic into the library ​     // bindWidget gives the Library a chance to insert logic into the library ​
     // widgets (WLibrary and WLibrarySidebar).     // widgets (WLibrary and WLibrarySidebar).
-    void bindWidget(WLibrarySidebar* sidebarWidget,​ +    void bindWidget( 
-                    WLibrary* libraryWidget,​ +            ​WLibrarySidebar* sidebarWidget,​ 
-                    MixxxKeyboard* pKeyboard);+            WLibrary* libraryWidget,​ 
 +            MixxxKeyboard* pKeyboard);
                     ​                     ​
     // Add a LibraryFeature to the list of features enabled in the Library.     // Add a LibraryFeature to the list of features enabled in the Library.
Line 585: Line 633:
   auto bufferSize = 256; // this avoids uninitialised locals   auto bufferSize = 256; // this avoids uninitialised locals
   ​   ​
-  for (const auto& value: values) { // Type can't get wrong +  for (const auto& value : values) { // Type can't get wrong 
       qDebug() << "​blah:"​ << value;       qDebug() << "​blah:"​ << value;
   }   }
   ​   ​
-  for (auto* channel: *channels) {+  for (auto* channel : *channels) {
       channel->​process(bufferSize);​       channel->​process(bufferSize);​
   }   }
Line 660: Line 708:
 **Good:** **Good:**
 <code cpp-qt> <code cpp-qt>
-for (auto&&​ item: mutableContainer) {+for (auto&&​ item : mutableContainer) {
   // read and write item   // read and write item
  
  
-for (const auto& item: immutableContainer) {+for (const auto& item : immutableContainer) {
   // read only item   // read only item
  
Line 673: Line 721:
 ==== forward declared / strongly typed enums ==== ==== forward declared / strongly typed enums ====
  
-Use. Both the name of the enum type and its enumerated values should be written in CamelCase with the first letter capitalized.+Use. Both the name of the enum type and its enumerated values should be written in CamelCase with the first letter capitalized. Do not add new C style enums and please replace those with enum classes when you are working on code that uses them.
  
 <code cpp-qt> <code cpp-qt>
 enum class ChannelLayout { enum class ChannelLayout {
     Unknown,     Unknown,
-    Mono,     ​// 1 channel+    Mono, // 1 channel
     DualMono, // 2 channels with identical signals     DualMono, // 2 channels with identical signals
-    Stereo, ​  ​// 2 independent channels left/right+    Stereo, // 2 independent channels left/right
     // ...     // ...
 }; };
Line 703: Line 751:
   public:   public:
     Helper() {}     Helper() {}
-    Helper(int baz) : baz(baz) {}+    Helper(int baz): baz(baz) {}
     ​     ​
     int derivedResult() {     int derivedResult() {
-      ​return foo * bar * baz;+        ​return foo * bar * baz;
     }     }
     ​     ​
Line 723: Line 771:
     ​     ​
     int derivedResult() {     int derivedResult() {
-      ​return foo * bar * baz;+        ​return foo * bar * baz;
     }     }
     ​     ​
coding_guidelines.1550320790.txt.gz · Last modified: 2019/02/16 07:39 by beenisss