Differences

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

Link to this comparison view

dev:coding_style [2013/07/25 01:10]
tedfelix Add assertions section. Formatting.
dev:coding_style [2013/10/18 00:38] (current)
michael [Indentation - NO TAB CHARACTERS]
Line 7: Line 7:
 Class names are UpperCamelCase, method names are lowerCamelCase, non-public member variables are m_prefixedCamelCase, slot names start with "slot". Class names are UpperCamelCase, method names are lowerCamelCase, non-public member variables are m_prefixedCamelCase, slot names start with "slot".
  
-===== Indentation =====+===== Indentation -  NO TAB CHARACTERS =====
  
-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.)+Indentation is by four spaces (0x20) at a time.  There should be **no tab characters (0x09) 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.)
  
 +//NOTE: As of revision 13,509, Rosegarden has 8,691 tab characters in 287 files.  Rosegarden 10.02 had 9,598 tab characters in 262 files.  The good news is fewer tabs overall, but the bad news is 25 new files have tabs that never had tabs before.  New developers are ignoring this rule, apparently.//
 ===== Namespaces ===== ===== Namespaces =====
  
Line 99: Line 100:
 ===== Argument Alignment ===== ===== 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++>
Line 113: Line 114:
 </code> </code>
  
-  * If your ''('' is so far to the right that following the above rule isn't practical, then indent the remainder of the ''()'' block by 8 spaces.+If your ''('' is so far to the right that following the above rule isn't practical, then indent the remainder of the ''()'' block by 8 spaces.
  
 <code c++> <code c++>
Line 126: Line 127:
 ===== Comments ===== ===== Comments =====
  
-  * Use [[dev:doxygen|doxygen-style]] comments for class and function documentation <code>/** ... */</code> or <code>///</code>+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:
  
 ^ Code                  ^  Meaning                              ^ ^ Code                  ^  Meaning                              ^
Line 139: Line 140:
 //Note: %%//!!!%% causes problems for doxygen.  We might want to revise the above.  Adding a space avoids problems: %%// !!!%%// //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 c++>//</code> comments instead of C-style <code c++>/* */</code> comments (except as applies to writing comments specific to [[dev:doxygen|doxygen]].)
  
 <code c++> <code c++>
Line 165: Line 166:
 ===== #include Order ===== ===== #include Order =====
  
-Includes should try to follow the following pattern:+Includes should try to follow the following pattern (from local to global):
  
-<code c++>+<code>
 #include "MyHeader.h" #include "MyHeader.h"
  
Line 235: Line 236:
 ===== Variables ===== ===== 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++>
Line 252: Line 253:
 Note that you should not feel like you have to take this to ridiculous extremes.  Just bear it in mind, especially when it's something obscure enough you've just had to go look at the header or the API yourself to figure out what some static parameter was for. Note that you should not feel like you have to take this to ridiculous extremes.  Just bear it in mind, especially when it's something obscure enough you've just had to go look at the header or the API yourself to figure out what some static parameter was for.
  
-  * Sometimes variables are simple and disposable, and names like //i// or //n// are appropriate, but unless your variable is something extremely simple and obvious, like an iterator, then it is preferable to use more verbose variable names in order to give the people who follow you a year later some shred of a hint what you were thinking when you wrote the code.  This particularly egregious example does some rather complicated transformations that would have been crystal clear to the author at the time, but coming at it as a stranger, it's really just short of impossible to try to work out what the logic is supposed to do here.  //mi// and //ph// and //i// oh my.  It's just spectacularly impossible to maintain, so //avoid doing this//:+Sometimes variables are simple and disposable, and names like //i// or //n// are appropriate, but unless your variable is something extremely simple and obvious, like an iterator, then it is preferable to use more verbose variable names in order to give the people who follow you a year later some shred of a hint what you were thinking when you wrote the code.  This particularly egregious example does some rather complicated transformations that would have been crystal clear to the author at the time, but coming at it as a stranger, it's really just short of impossible to try to work out what the logic is supposed to do here.  //mi// and //ph// and //i// oh my.  It's just spectacularly impossible to maintain, so //avoid doing this//:
  
 <code c++> <code c++>
 
 
dev/coding_style.1374707413.txt.gz · Last modified: 2013/07/25 01:10 by tedfelix
Recent changes RSS feed Creative Commons License Valid XHTML 1.0 Valid CSS Driven by DokuWiki