NAudio Coding Guidelines

Naming Conventions - we follow the standard Microsoft recommended naming conventions for all parts of the public interface in NAudio. One of the best ways of learning about these is to get the "Framework Design Guidelines" book by Brad Abrams and Krzysztof Cwalina. You can view a summary here. The use of FxCop is also encouraged.

Unit Tests - wherever possible, unit tests (we use NUnit) should be written for new code and bugfixes. Tests should be written in such a way that they should run and pass simply if you get the latest code and build it. We may need to work out a way of segregating our tests so that they can be categorised according to what systems and environments they can be run on as not all systems support all the types of test we will want to do.

Interop - NAudio contains a lot of interop code both with standard DLLs and COM objects. The interop wrappers themselves should not be made public. Rather, wrapper classes with a more intuitive interface should be used. Error codes should be turned into exceptions with meaningful descriptions wherever possible. Comments linking to MSDN documents and Windows SDK header file locations are encouraged.

Comments - all public classes should be properly commented using XML comments. NAudio does not follow a convention of putting copyright or author information in comments at the top of individual files (with the exception of when we accept third party code). To credit yourself for work you added, do so in the changes.xml file which is part of the NAudio solution (see below).

Features - we intend to use the CodePlex issues tracker to indicate planned and current work. This will provide a place to discuss and debate any design decisions. Please keep the project coordinator informed of what you plan to do. As a general rule, bug fixing and the addition of new features are always welcome, but changes to the interface of existing public components need to be discussed first.

Checking In - only check in code that builds with no errors or warnings. You should not check in if your code breaks any tests that previously passed. However, you can add new tests that do not yet pass. Work in progress can be checked in, but not if it leaves existing functionality broken. You must add comments to say what you checked in. If you modify the core NAudio DLL, you should add a new section to the changes.xml file. This includes the date, a new version number (simply increment the build number), a list of changes you made, and your name.

Code Reviews - you should expect other developers on the project to code review your checkin and report suggestions for improvement or fixing. You are encouraged to do the same for other developer's checkins.

Portability - NAudio is not likely to work on different platforms due to the large amount of interop. However, public code should be CLS compliant where possible, and thought should be given to letting VB and other languages access all features. NAudio currently has not been tested on 64 bit Windows, but code should be written with it in mind so the amount of fixes required in the future is kept minimal.

Source Control - The NAudio project files must not have any source control information added to them.

Last edited Jun 11, 2008 at 1:09 PM by markheath, version 1


No comments yet.