CodingStandards

From Audacity Wiki
Jump to: navigation, search
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):

Contents

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.
  • Source files are in UTF-8 format (so they may contain accented and other characters where necessary). This ensures they are processed the same by all compilers on all platforms
  • When committed to SVN, all source files have the 'svn:eol-style' property set to 'native' so that when they are checked out they are automatically given the correct line endings for the platform you are working on.

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.

Personal tools

Donate securely by PayPal, using your credit card or PayPal account!