Skip to content
This repository has been archived by the owner on Dec 6, 2024. It is now read-only.

Contribution Guidelines

Jump to bottom
Peter Palotas edited this page Jun 6, 2017 · 3 revisions

Writing Code

This section contains guidelines for how to write code when contributing to AlphaFS.

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.

Naming

Settings for Tabs and Spaces

  • X DO NOT use tabs in files (use spaces)
  • √ DO use an indentation level of three (3) spaces.

General Naming Conventions

  • √ DO choose easily readable identifier names.
  • √ DO favor readability over brevity.
    • The property name CanScrollHorizontally is better than ScrollableX (an obscure reference to the X-axis).
  • √ DO use PascalCasing for all public member, type, and namespace names consisting of multiple words.
  • √ DO use camelCasing for parameter names.
  • √ DO use camelCasing with an m_ prefix for private or protected field names.
    • For example m_currentContext.
  • √ DO use camelCasing with an s_ prefix for private or protected static field names.
  • X DO NOT use underscores, hyphens, or any other nonalphanumeric characters in public types or members.
  • X DO NOT use abbreviations or contractions as part of identifier names
    • For example, use GetWindow rather than GetWin.

Names of Classes, Structs and Interfaces

  • √ DO follow these Microsoft Guidelines, except for the following.
  • √ DO use the original name of internal structures/classes/enumerations/members that represent native Win32 objects.
    • For example use WIN32_STREAM_ID for an internal structure representing the Win32 structure with the same name, instead of Win32StreamId.
    • Keep the names of members of structures as defined in the Win32-API as well.

Regions

  • √ DO use regions to group various parts of a class together.
    • For example having one region for properties, one for methods etc.
  • AVOID using nested regions.
    • Nested regions makes navigating the code slower and more cumbersome. The automatic collapsing of methods and comments in Visual Studio is usually good enough.
    • Prefer splitting class into multiple files instead, or using comments.

Resources

  • √ DO use resources (resx) to refer to any strings that are messages that may be displayed to a user.

Exceptions

  • √ DO derive your exceptions classes from the most specific .NET exception that matches your error.
    • For example most of the exceptions in AlphaFS derives from IOException.
  • √ DO set the error code properly when creating an exception that derives from IOException.

Documentation

  • √ DO document all public types and members with XML documentation 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.
    • Pull-requests with EMPTY documentation tags are not allowed.
  • √ DO ensure that the Sandcastle project builds without any warnings before pushing changes.
  • √ DO update the Changelog.md file to indicate any changes that affect users of the code, bug fixes or new features.

Breaking Changes

  • X DO NOT introduce breaking changes if it can be avoided.
  • √ DO clearly document any breaking changes in the changelog and mark them as 'Breaking'

Code Analysis

  • √ DO run code-analysis on the project before committing changes. No code analysis warnings must be present.
    • This is normally done automatically when building.
  • √ DO add the Justification property to any SuppressMessage attribute that needs to be added, explaining why you are suppressing that issue.

Testing

The so called "unit tests" of AlphaFS are mostly integration tests rather than unit tests, since they do use the filesystem and therefore do not need to adhere strictly to the common unit test conventions such as one assertion per test. Mocks or fakes are not normally used.

  • √ DO write automated tests to test any new code, or modified code that does not already have tests.
  • √ DO place the tests in a class with the same name as the class they are testing, suffixed by Tests
    • For example DirectoryInfoTests
  • CONSIDER splitting the class into multiple partial classes in different files if the class is large. Follow the same file pattern as the original class.
  • √ DO use the pattern <function>_<scenario>_<expected result> to name your tests.
    • For example Open_NullName_ThrowsArgumentNullException or
    • WriteAllText_ExistingFileWithOverwriteSetToTrue_OverwritesTheExistingFile
  • AVOID testing multiple functions in the same test method.
    • It is often required to use multiple methods, but the assertions should generally deal with a single method.
  • √ DO ensure that testing is performed with both local and UNC paths.
  • √ DO ensure that all tests run successfully before pushing any changes or creating a pull-request.

Working with AlphaFS on GitHub

  • √ DO create an issue detailing the changes you are about to make before starting work on them.
  • √ DO add the In Progress label to any issue that you've started working on, and assign it to yourself.
  • √ DO associate your commits with the issue you are working on. For more information about how to automatically close an issue when committing, see https://help.github.com/articles/closing-issues-via-commit-messages/
  • √ DO write some information about what you have done in your commit messages.
    • Just writing "WIP" or "temp" or something does makes it more difficult to browse history.

For contributors with write access to the repository

  • Follow the Git Flow branching model.
    • Never commit anything directly to the master branch. Only merging to this branch is allowed.
  • AVOID pushing major- or breaking changes directly to the develop branch.
    • Anything that isn't a very minor change should be created on a feature branch and have a pull-request created and be reviewed and merged by another contributor.
Clone this wiki locally