Proposed Enhancements to PortAudio API

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.

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:

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:

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:

Naming Conventions

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.

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.