ImplementationStyleGuidelines

h1. Implementation style guidelines

This page provides coding guidelines for PortAudio contributors. Some of the guidelines pertain to mechanical style, others to quality of implementation issues. Since the PortAudio code is commonly edited on many different platforms using different editors, these guideline should be followed to improve readability and consistency.

h2. PortAudio API design guidelines

The design guidelines of the PortAudio project are restated here as some of them apply to implementation as well as to API design.

• Implementation should be possible on all common computer music platforms.
• Clients of PortAudio should be able to gain efficient, and ideally optimal use of the audio services on all target platforms.
• The API should be simple enough to be used by music students with minimal experience in C programming.
• The API should seek to provide only low-level audio services, and to only support those services directly available on the host platform.

Note that the last guideline has been relaxed with regard to audio sample formats and user buffer sizes - PortAudio can convert between a number of sample formats and can adapt to the user's buffer size requirements.

h2. Formatting conventions

The following formatting conventions should be adhered to in all PortAudio code:

• TABs should not be used in .c and .h files; instead 4 spaces should be used. Makefiles should continue to use TABs since this is required by Make.
• Line-end characters will be consistent with the platform on which the source has been checked out of SVN (SVN handles this).
• Brace placement will follow ANSI style:

if( aCondition )
{
    DoSomething();
}
else
{
    DoSomethingElse();
}

• C-Style comments should be used:

/* this comment is OK */
// this comment is NOT OK

h2. Tools for checking code compliance to style guidelines

"AStyle":http://astyle.sourceforge.net <"http://astyle.sourceforge.net":http://astyle.sourceforge.net> has been proposed as helpful tool for cleaning code, however we don't intend to use it on an ongoing basis. It is expected that contributors of each implementation will take responsibility for keeping their code clean.

h2. Quality of implementation guidelines

The following coding guidelines should be followed in order to establish a quality baseline for our implementations:

• All code should be written in C++-compatible plain ANSI C. It has been suggested that all implementations should compile silently with both "@gcc -ansi -pedantic -Wall@" and "@g++ -ansi -pedantic -Wall@"
• Think of PortAudio as a heavyweight library rather than a lightweight wrapper. Always code defensively. Efficiency is important where it matters (e.g. in real-time callbacks) but safety is important everywhere.
• All parameters passed to PortAudio by the user should be validated, and error codes returned where necessary. All reasonable efforts should be made to minimise the risk of a crash resulting from passing incorrect parameters to PortAudio.
• Error handling should be complete. Every host function that can return an error condition should have its status checked. PortAudio may attempt to recover from errors in some cases, but generally error codes should be returned to the client.
• In almost all cases, a PortAudio error code should be preferred to returning @PaHostError@. If a new PortAudio error code is needed it should be discussed with the maintainer to coordinate updating portaudio.h
• PortAudio code should not cause resource leaks. After @Pa_Terminate()@ is called, implementations should guarantee that all dynamically allocated resources have been freed.
• The definition of the PortAudio API should minimise "implementation defined behaviour". For example, calling functions such as @Pa_Initialize()@ after PortAudio is initialised, or @Pa_Terminate()@ after PortAudio has been terminated has well defined behaviour.
• Minimise dependence on ANSI C runtime on platforms where it would have to be loaded separately (e.g. on Win32 prefer Win32 API functions such as @GlobalAlloc()@ to ANSI C functions such as @malloc()@).

It has been suggested that we make an effort to minimise the use of global and static data in PortAudio implementations. Another related goal is to reduce name pollution in the global scope. Some possible guidelines in this regard are:

• Implementations should avoid exporting any symbols except where absolutely necessary. Specifically, global data must be declared statically. The next section documents naming conventions for all PortAudio symbols.
• Implementations should minimise their use of static data.

h2. Naming conventions

• All @#defines@ begin with @PA_@
• All @#defines@ local to a file end with @_@
• All global utility variables begin with @paUtil@
• All global utility types begin with @PaUtil@ (including function types)
• All global utility functions begin with @PaUtil_@
• All static variables end with @_@
• All static constants begin with @const@ and end with @@ (e.g.: @constMyMagicNumber@)
• All static functions have no special prefix/suffix
• Platform-specific shared functions should begin with @Pa@_ where @PN@ is the platform name. eg. @PaWin_@ for Windows, @PaUnix_@ for Unix.

In general, implementations should declare all of their members static, except for their initializer which should be exported. All exported names should be preceded by @Pa_@ where @@ is the module name, for example the Windows MME initializer should be named @PaWinMme_Initialize()@.

If it is necessary for implementations to define non-static symbols, they should use the following naming conventions, where is the module name such as WinMme.

• global variables should begin with @pa@
• global types should begin with @Pa@
• global utility functions should begin with @Pa_@

h2. Debug message logging

Two utilities for debug messages are provided:

• The PA_DEBUG macro defined in @pa_debugprint.h@ provides a simple way to print debug messages to stderr. In order to enable this feature, PortAudio should be built with @PA_ENABLE_DEBUG_OUTPUT@ defined (passing the @--enable-debug-output@ flag to the configure script or setting it in the "Preprocessor definitions"). Due to real-time performance issues, @PA_DEBUG@ may not be suitable for use within the PortAudio processing callback, or in other threads.
• When real-time event tracing is required it is best to use the facility provided in @pa_trace.h@ may be more appropriate. In order to enabled this feature, @PA_TRACE_REALTIME_EVENTS@ should be set to 1 in the file @pa_trace.h@ when building PortAudio. If @PA_LOG_API_CALLS@ is defined, all calls to the public PortAudio API will be logged to stderr along with parameters and return values.