AlphaFS Development Guidelines

Overview

AlphaFS is a library that replicates the well-known interfaces and style of classes used for file system access in the .NET framework, but adds additional capabilities within this realm. AlphaFS is not simply a P/Invoke wrapper and should not expose native API's directly, but rather convert them into the familiar .NET style.

Writing Code

Text Editor Settings

The Visual Studio 2010 settings to use for formatting of C# files is attached to this page and can be downloaded from here: AlphaFS-CSText.vssettings
  • Configure Visual Studio to use Spaces and not Tabs
  • Set the tab with to be 3 spaces.
(Currently the usage of tabs/spaces varies throughout the code. Feel free to use Ctrl-K, Ctrl-D in Visual Studio to automatically reformat the file if you have the correct settings).

Follow Naming Conventions and formatting

  • All public classes and methods must use standard .NET naming conventions.
  • Look at existing code and follow the same patterns for naming private members and formatting your code.

Document ALL public types, members and parameters

All public types, methods, parameters and return values must be properly documented using XML-Doc comments. The documentation should follow the style of the normal MSDN documentation for the .NET framework, however does not normally need any examples nor be as verbose as the MSDN documentation often is.

The documentation should state in plain and clear english the purpose and function of a type, method parameter and return value.

Because of this rule, missing documentation is treated as errors when building.

Check-ins with EMPTY documentation tags are not allowed.

Document significant changes in code

When adding or moving code, or making significant modifications add normal comments with your name followed by e brief description of what you've done and why. If not appropriate to put this in the code, place it in the comment of your check-in.

Example:
// 2012-01-31: Yomodo; Moved to: Filesystem\Enumerations\GetFileExInfoStandard.cs as Win32FileAttributeData struct.


When fixing a significant bug or adding new functionality add information about this in the Changelog.txt file.

Do NOT break the publicly released API (unless you really, really need to)

Do not modify the public interface of any class or method that has already been released without serious consideration. Prefer marking an existing method as Obsolete (using the attribute). If absolutely necessary, make a note in the Changelog.txt, clearly marking this as a breaking change.

This also means do not use default parameters as long as we target a framework prior to .NET 4. (C# in Visual Studio 2008 does not support default parameters, meaning adding a default parameter to a method actually changes its signature for those users)

Run Code Analysis

Run CodeAnalysis (or FxCop) using the supplied ruleset before any check-in. There must be no CodeAnlysis warnings. If you need to suppress a warning, suppress it in code and add a justification to the attribute.

Use Work-Items (issues)

Always associate a check-in with a work-item. Set the work item as 'Active' when you're actively working on it, and Close the work item when you are done with it. Also set the iteration path (or 'Release') when creating work items so we know the planned release for them.

Write Tests

Whenever applicable unit tests should be written for any new or modified functionality.

Note that the term "unit test" is used quite loosely here and does not necessarily mean a pure unit test. With a "unit test" we refer to any automated test that is written in the MSTest framework. Most of these tests would probably be better categorized as "integration tests" rather than pure unit tests.

Run all tests before check-in

Before checking in any modifications to the code base, run all unit tests and make sure they pass before checking in.

Last edited May 1, 2012 at 4:33 PM by decaf, version 6