Difference between revisions of "CodingStandards"

From Audacity Wiki
Jump to: navigation, search
m (Do's and Don't's: This mistake is now a compile error - so it get found quicker, but more painfully.)
Line 26: Line 26:
 
'''Do's:'''
 
'''Do's:'''
 
* Ensure declaration and definition use the same type (not typedefed names that happen to be the same).
 
* Ensure declaration and definition use the same type (not typedefed names that happen to be the same).
* Ensure when using functions like ''wxPrintf, wxString::Format, wxString::Printf'' and passing a wxString, the ''wxString::c_str()'' method is used to pass the correct value.  Otherwise, non-Visual C (GCC) generated code WILL fail at runtime.
+
* Ensure when using functions like ''wxPrintf, wxString::Format, wxString::Printf'' and passing a wxString, the ''wxString::c_str()'' method is used to pass the correct value.  Otherwise, a compilation error will occur with the GCC compiler (Mac and Linux systems).
 
* Place user interface strings inside _() (not wxT() which is used for non-translated or testing-only strings). This ensures gettext can extract the strings for translation. Any strings that are context-dependent or need explanation should be prefaced with a comment starting "i18n-hint:".  
 
* Place user interface strings inside _() (not wxT() which is used for non-translated or testing-only strings). This ensures gettext can extract the strings for translation. Any strings that are context-dependent or need explanation should be prefaced with a comment starting "i18n-hint:".  
  
 
'''Don't's:'''
 
'''Don't's:'''
 
* Prefix member functions with the class name in the header - it's a GCC compiler error.
 
* Prefix member functions with the class name in the header - it's a GCC compiler error.
 
  
 
==Header comments==
 
==Header comments==

Revision as of 14:54, 2 February 2013

While we're not particularly insistent about coding standards, there are a few things that we try to do consistently as below.
 
Related article(s):

Conventions

When modifying existing files, the main things are:

  • spaces, no tabs
  • three spaces per indent

As far as naming:

  • classes and methods/functions are in CamelCase
  • local variables are firstLoweredCamelCase
  • member variables are mVar
  • globals are usually gVar


Preferences

  • Our style (and that of wxWidgets) is to not leave a space between a function name like 'GetAllFormats' and the following '(', so please copy that style too. It can make searching for functions easier.
  • If you're defining a complex macro, add a comment. You may understand it without a comment. We might not.
  • When you're using a #ifdef to give different bodies to a function, and the function is fairly long, we prefer that the #ifdef include the function header, the '{' and the closing '}' inside it rather than 'sharing' them between the two versions. We think the slight duplication is worth it for the better readability.


Do's and Don't's

Do's:

  • Ensure declaration and definition use the same type (not typedefed names that happen to be the same).
  • Ensure when using functions like wxPrintf, wxString::Format, wxString::Printf and passing a wxString, the wxString::c_str() method is used to pass the correct value. Otherwise, a compilation error will occur with the GCC compiler (Mac and Linux systems).
  • Place user interface strings inside _() (not wxT() which is used for non-translated or testing-only strings). This ensures gettext can extract the strings for translation. Any strings that are context-dependent or need explanation should be prefaced with a comment starting "i18n-hint:".

Don't's:

  • Prefix member functions with the class name in the header - it's a GCC compiler error.

Header comments

If you're adding new files into Audacity source there is boilerplate header we like to use:


/**********************************************************************

   Audacity: A Digital Audio Editor
   Audacity(R) is copyright (c) 1999-2008 Audacity Team.
   License: GPL v2.  See License.txt.

   AudacityApp.cpp
   Dominic Mazzoni, Leland Lucius

******************************************************************//**

\class AudacityApp
\brief AudacityApp is the 'main' class for Audacity 

It handles initialization and termination by subclassing wxApp.

*//*******************************************************************/


Some files will have wxWidgets license rather than GPL. The second part of the header, starting with the line ending in //** is a Doxygen  class-level comment on the class defined within the source file.


Doxygen Elsewhere

We're also slowly moving towards more Doxygen  friendly code, so comments at the start of functions with the Doxygen ///   marker are encouraged. We're not planning on having everything Doxygenated. We do aim to have doxygen comments at the class level for all classes.


Header files

Note that some header files (.h) don't contain class declarations for classes defined in the corresponding C++ files (.cpp). These are described at Unusual Header Files; note in particular the Guidelines for using Experimental.h.