014 - Implementation Style Guidelines

Enhancement Proposals Index, PortAudio Home Page

Updated: July 26, 2002

Introduction

This document provides coding guidelines for PortAudio implementors. Some of the guildelines 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.

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 final 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.

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 CVS (CVS handles this.)
• Brace placement will follow ANSI style, eg:

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

AStyle ( 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.

[META]Provide comment format and style guidelines, since every file seems to use a different commenting style for no good reason.[/META]

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 (i.e. no // comments). 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 (eg 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 (eg 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.

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 _ (eg: constMyMagicNumber_)
• All static funtions 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 preceeded 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_

Debug Message Logging

Two utilities for debug messages are provided. The PA_DEBUG macro defined in pa_implementation.h provides a simple way to print debug messages to stderr. Due to real-time performance issues, PA_DEBUG may not be suitable for use within the portaudio processing callback, or in other threads. In such cases the event tracing facility provided in pa_trace.h may be more appropriate.

If PA_LOG_API_CALLS is defined, all calls to the public PortAudio API will be logged to stderr along with parameter and return values.