Rosegarden Wiki

 

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
Next revision Both sides next revision
dev:coding_style [2013/07/05 15:07]
127.0.0.1 external edit 		dev:coding_style [2013/07/24 23:10]
tedfelix Add assertions section. Formatting.
Line 1: Line 1:
- 
 ====== Rosegarden Coding Style ====== ====== Rosegarden Coding Style ======
  
 Rosegarden house style is as follows, in approximately descending order of importance: Rosegarden house style is as follows, in approximately descending order of importance:
  
-  * Class names are UpperCamelCase, method names are lowerCamelCase, non-public member variables are m_prefixedCamelCase, slot names start with "slot".+===== Names =====
  
-  * Indentation is by four spaces at a time.  There should be **no tab characters anywhere** in Rosegarden source code.  The indentation should look the same regardless of whether you read it in an IDE, in a terminal window with "cat" or "vi", in Emacs, or quoted in an email. It **must not** depend on having the right settings for tab-to-space conversion in your IDE when you read it.  (Emacs and vim users will note that we already start every source file with a meta-comment that sets up the right indentation mode in these editors.)+Class names are UpperCamelCase, method names are lowerCamelCase, non-public member variables are m_prefixedCamelCase, slot names start with "slot".
  
-  * Use [[dev:doxygen|doxygen-style]] comments for class and function documentation <code>/** ... */</code> or <code>///</code>+===== Indentation ===== 
 + 
 +Indentation is by four spaces at a time.  There should be **no tab characters anywhere** in Rosegarden source code.  The indentation should look the same regardless of whether you read it in an IDE, in a terminal window with "cat" or "vi", in Emacs, or quoted in an email. It **must not** depend on having the right settings for tab-to-space conversion in your IDE when you read it.  (Emacs and vim users will note that we already start every source file with a meta-comment that sets up the right indentation mode in these editors.) 
 + 
 +===== Namespaces =====
  
-  * No extra indentation inside namespaces; set off inner code by two carriage returns on either side of namespace brackets+No extra indentation inside namespaces; set off inner code by two carriage returns on either side of namespace brackets
  
 <code c++> <code c++>
Line 26: Line 29:
 </code> </code>
  
-  * Braces are what you might call Java-style, which means:+===== Braces ===== 
 + 
 +Braces are what you might call Java-style, which means:
  
 <code c++> <code c++>
Line 44: Line 49:
 </code> </code>
  
-  * Single statement blocks are preferably either "inline" or bracketed.  Like this:+===== if ===== 
 + 
 +Single statement blocks are preferably either "inline" or bracketed.  Like this: 
 <code c++> <code c++>
-   if (something) somethingElse(); +if (something) somethingElse(); 
-   else someOtherThing(); +else someOtherThing(); 
-   if (something) { + 
-       somethingElse(); +if (something) { 
-   } else { +    somethingElse(); 
-       someOtherThing(); +} else { 
-   }+    someOtherThing(); 
 +}
 </code> </code>
  
Line 58: Line 67:
  
 <code c++> <code c++>
-   if (something) +if (something) 
-       somethingElse();+    somethingElse();
 </code> </code>
  
-  * Whitespace is much as in the above examples (outside but not inside ''()'', after but not before '';'', etc.):+===== Parentheses and Whitespace ===== 
 + 
 +Whitespace is much as in the above examples (outside but not inside ''()'', after but not before '';'', etc.):
 <code c++> <code c++>
-    connect(detailsButton, SIGNAL(clicked(bool)), this, SLOT(slotDetails()));+connect(detailsButton, SIGNAL(clicked(bool)), this, SLOT(slotDetails()));
 </code> </code>
  
Line 70: Line 81:
  
 <code c++> <code c++>
-    connect( detailsButton, SIGNAL( clicked(bool) ), this, SLOT( slotDetails() ) );+connect( detailsButton, SIGNAL( clicked(bool) ), this, SLOT( slotDetails() ) );
 </code> </code>
  
Line 76: Line 87:
  
 <code c++> <code c++>
-    if( something) +if( something) 
-    if(something)+if(something)
 </code> </code>
  
 No whitespace between ''if'' (and other C++ keywords) and the ''('' makes Michael's eyes hurt. No whitespace between ''if'' (and other C++ keywords) and the ''('' makes Michael's eyes hurt.
  
-  * Pointers are ''MyObject *ptr;'' not ''MyObject* ptr;''+===== Pointers ===== 
 + 
 +Pointers are ''MyObject *ptr;'' not ''MyObject* ptr;'' 
 + 
 +===== Argument Alignment =====
  
   * If you have more arguments than will fit on a reasonable length line (80 characters is a good figure, but this is not a hard rule), align the extra arguments below and just after the opening ( rather than at a new level of indentation:   * If you have more arguments than will fit on a reasonable length line (80 characters is a good figure, but this is not a hard rule), align the extra arguments below and just after the opening ( rather than at a new level of indentation:
 +
 <code c++> <code c++>
-    connect(m_pluginList, SIGNAL(activated(int)), +connect(m_pluginList, SIGNAL(activated(int)), 
-            this, SLOT(slotPluginSelected(int)));+        this, SLOT(slotPluginSelected(int)));
 </code> </code>
  
Line 93: Line 109:
  
 <code c++> <code c++>
-    connect(m_pluginList, SIGNAL(activated(int)), +connect(m_pluginList, SIGNAL(activated(int)), 
-        this, SLOT(slotPluginSelected(int)));+    this, SLOT(slotPluginSelected(int)));
 </code> </code>
  
Line 100: Line 116:
  
 <code c++> <code c++>
-        CommandHistory::getInstance()->addCommand(new SegmentSyncCommand( +CommandHistory::getInstance()->addCommand(new SegmentSyncCommand( 
-                comp.getSegments(), selectedTrack, +        comp.getSegments(), selectedTrack, 
-                dialog.getTranspose(), +        dialog.getTranspose(), 
-                dialog.getLowRange(), +        dialog.getLowRange(), 
-                dialog.getHighRange(), +        dialog.getHighRange(), 
-                clefIndexToClef(dialog.getClef()))); +        clefIndexToClef(dialog.getClef())));
 </code> </code>
                                                          
 +===== Comments =====
 +
 +  * Use [[dev:doxygen|doxygen-style]] comments for class and function documentation <code>/** ... */</code> or <code>///</code>
  
   * Use comment codes in your comments when appropriate:   * Use comment codes in your comments when appropriate:
Line 119: Line 137:
 | <code>//$$$</code>    | Strings to change after a freeze ends | | <code>//$$$</code>    | Strings to change after a freeze ends |
  
 +//Note: %%//!!!%% causes problems for doxygen.  We might want to revise the above.  Adding a space avoids problems: %%// !!!%%//
  
   * If in doubt, please err on the side of putting in too many comments.  We have contributors of all ability levels working here, and what may seem obvious to you might be complete gibberish to someone else.  Comments give everyone a better chance to be useful, and they are always welcome, while nobody will think you are a super code warrior or code gazelle for committing a thousand lines that have only three choice comments   * If in doubt, please err on the side of putting in too many comments.  We have contributors of all ability levels working here, and what may seem obvious to you might be complete gibberish to someone else.  Comments give everyone a better chance to be useful, and they are always welcome, while nobody will think you are a super code warrior or code gazelle for committing a thousand lines that have only three choice comments
  
   * When commenting out a large block of text, it is preferable to use C++ style <code>//</code> comments instead of C-style <code>/* */</code> comments (except as applies to writing comments specific to [[dev:doxygen|doxygen]].)   * When commenting out a large block of text, it is preferable to use C++ style <code>//</code> comments instead of C-style <code>/* */</code> comments (except as applies to writing comments specific to [[dev:doxygen|doxygen]].)
 +
 <code c++> <code c++>
 //&&& This code was deleted temporarily //&&& This code was deleted temporarily
Line 140: Line 160:
     } */     } */
 </code> </code>
 +
 (The reason C++-style comments are preferred is not arbitrary.  C++-style comments are much more obvious when viewing diffs on the rosegarden-bugs list, because they force the entire block of text to be displayed, instead of only the starting and ending lines.) (The reason C++-style comments are preferred is not arbitrary.  C++-style comments are much more obvious when viewing diffs on the rosegarden-bugs list, because they force the entire block of text to be displayed, instead of only the starting and ending lines.)
  
-  * Includes should try to follow the following pattern: +===== #include Order ===== 
-<code>+ 
 +Includes should try to follow the following pattern: 
 + 
 +<code c++>
 #include "MyHeader.h" #include "MyHeader.h"
  
Line 159: Line 183:
 </code> </code>
  
-  * Switch statements are all over the place, and we need to pick one style and use it, so we'll call this a good switch statement: +===== Switch =====
-<code c++> +
-    switch (hfix) {+
  
-    case NoteStyle::Normal: +Switch statements are all over the place, and we need to pick one style and use it, so we'll call this a good switch statement: 
-    case NoteStyle::Reversed: +<code c++> 
-        if (params.m_stemGoesUp ^ (hfix == NoteStyle::Reversed)) { +switch (hfix) {
-            s0.setX(m_noteBodyWidth - stemThickness); +
-        } else { +
-            s0.setX(0); +
-        } +
-        break;+
  
-    case NoteStyle::Central: +case NoteStyle::Normal: 
-        if (params.m_stemGoesUp ^ (hfix == NoteStyle::Reversed)) { +case NoteStyle::Reversed: 
-            s0.setX(m_noteBodyWidth / 2 + 1); +    if (params.m_stemGoesUp ^ (hfix == NoteStyle::Reversed)) { 
-        } else { +        s0.setX(m_noteBodyWidth - stemThickness); 
-            s0.setX(m_noteBodyWidth / 2); +    } else { 
-        } +        s0.setX(0);
-        break;+
     }     }
 +    break;
  
 +case NoteStyle::Central:
 +    if (params.m_stemGoesUp ^ (hfix == NoteStyle::Reversed)) {
 +        s0.setX(m_noteBodyWidth / 2 + 1);
 +    } else {
 +        s0.setX(m_noteBodyWidth / 2);
 +    }
 +    break;
 +}
 </code> </code>
  
Line 186: Line 211:
  
 <code c++> <code c++>
-    switch(layoutMode) { +switch(layoutMode) { 
-        case 0 : +    case 0 : 
-            findAction("linear_mode")->setChecked(true); +        findAction("linear_mode")->setChecked(true); 
-            findAction("continuous_page_mode")->setChecked(false); +        findAction("continuous_page_mode")->setChecked(false); 
-            findAction("multi_page_mode")->setChecked(false); +        findAction("multi_page_mode")->setChecked(false); 
-            slotLinearMode(); +        slotLinearMode(); 
-        break; +    break; 
-        case 1 : +    case 1 : 
-            findAction("linear_mode")->setChecked(false); +        findAction("linear_mode")->setChecked(false); 
-            findAction("continuous_page_mode")->setChecked(true); +        findAction("continuous_page_mode")->setChecked(true); 
-            findAction("multi_page_mode")->setChecked(false); +        findAction("multi_page_mode")->setChecked(false); 
-            slotContinuousPageMode(); +        slotContinuousPageMode(); 
-        break; +    break; 
-        case 2 : +    case 2 : 
-            findAction("linear_mode")->setChecked(false); +        findAction("linear_mode")->setChecked(false); 
-            findAction("continuous_page_mode")->setChecked(false); +        findAction("continuous_page_mode")->setChecked(false); 
-            findAction("multi_page_mode")->setChecked(true); +        findAction("multi_page_mode")->setChecked(true); 
-            slotMultiPageMode(); +        slotMultiPageMode(); 
-        break; +    break; 
-    }+}
 </code> </code>
 +
 +===== Variables =====
  
   * You should feel encouraged to use variables to make the code easier to understand without a look at the header or the API docs.  Good:   * You should feel encouraged to use variables to make the code easier to understand without a look at the header or the API docs.  Good:
  
 <code c++> <code c++>
-    int spacing = 3; +int spacing = 3; 
-    bool useHoops = false;+bool useHoops = false;
          
-    doSomething(spacing, useHoops);+doSomething(spacing, useHoops);
 </code> </code>
  
Line 220: Line 247:
  
 <code c++> <code c++>
-    doSomething(3, false);+doSomething(3, false);
 </code> </code>
  
Line 228: Line 255:
  
 <code c++> <code c++>
-    int i; +int i; 
-    int mi = -2; +int mi = -2; 
-    int md = getLineSpacing() * 2;+int md = getLineSpacing() * 2;
  
-    int testi = -2; +int testi = -2; 
-    int testMd = 1000;+int testMd = 1000;
  
-    for (i = -1; i <= 1; ++i) { +for (i = -1; i <= 1; ++i) { 
-        int d = y - getSceneYForHeight(ph + i, x, y); +    int d = y - getSceneYForHeight(ph + i, x, y); 
-        if (d < 0) { +    if (d < 0) { 
-            d = -d; +        d = -d;
-        } +
-        if (d < md) { +
-            md = d; +
-            mi = i; +
-        } +
-        if (d < testMd) { +
-            testMd = d; +
-            testi = i; +
-        }+
     }     }
 +    if (d < md) {
 +        md = d;
 +        mi = i;
 +    }
 +    if (d < testMd) {
 +        testMd = d;
 +        testi = i;
 +    }
 +}
 </code> </code>
  
-  * Menu items:+===== Assertions ===== 
 +Use Q_ASSERT_X() from <QtGlobal> for assertions. 
 + 
 +<code c++> 
 +Q_ASSERT_X(id < m_refreshStatuses.size(), 
 +           "RefreshStatusArray::getRefreshStatus()",  // where 
 +           "ID out of bounds");                       // what 
 +</code> 
 + 
 +Make sure errors are properly handled in a non-debug build.  Do not depend on assertions. 
 + 
 +<code c++> 
 +Q_ASSERT_X(p, "foo()", "null pointer"); 
 +if (!p) { 
 +    return; 
 +} 
 +</code> 
 + 
 +===== Menu Items =====
  
 Menu items use [[http://en.wikipedia.org/wiki/Capitalization#Titles|title case]].  We don't capitalize pronouns except pronouns "standing alone" (exhaustive pronouns).  For instance, "Move to Staff Above". Menu items use [[http://en.wikipedia.org/wiki/Capitalization#Titles|title case]].  We don't capitalize pronouns except pronouns "standing alone" (exhaustive pronouns).  For instance, "Move to Staff Above".
Line 259: Line 304:
 For example: For example:
  
-<code> +<code xml> 
-    <Action name="general_move_events_up_staff"  +<Action name="general_move_events_up_staff"  
-     text="&amp;Move to Staff Above..." />+        text="&amp;Move to Staff Above..." />
 </code> </code>
  
Line 268: Line 313:
   * [[layout_code|Qt Layouts]]   * [[layout_code|Qt Layouts]]
   * [[[config_groups]Config Groups]]   * [[[config_groups]Config Groups]]
- 
  
 
dev/coding_style.txt · Last modified: 2022/05/06 16:07 (external edit)
Recent changes RSS feed Creative Commons License Valid XHTML 1.0 Valid CSS Driven by DokuWiki