Skip to content

Latest commit

 

History

History
461 lines (354 loc) · 11.7 KB

CONTRIBUTING.md

File metadata and controls

461 lines (354 loc) · 11.7 KB
Raw

Contributing to the project

Thanks for taking the time to contribute! ✨

In this document you will find all the information you need to make sure the project continues to be the high-quality product we want to be!

Reporting issues

Issues

When reporting a problem, be as specific as possible. Ideally, you should provide an small snippet of code that reproduces the issue. Try to provide also the following information:

  • OS: Linux / Windows / Mac OS
  • Runtime: .NET Framework, Mono, .NET Core
  • Version of the product
  • Stacktrace if any
  • What's happening and what you expect to happen

Features

If you want to ask for a new feature, first make sure it hasn't been reported yet by using the search box in the issue tab. Make sure that the feature aligns with the direction of the project.

Pull Request

Before starting a pull request, create an issue requesting the feature you would like to see and implement. If you are fixing a bug, create also an issue to be able to track the problem. State that you would like to work on that. The team will reply to the issue as soon as possible, discussing the proposal if needed. This guarantee that later on the Pull Request we don't reject the proposal without having a discussion first and we don't waste time.

In general, the process to create a pull request is:

  1. Create an issue describing the bug or feature and state you would like to work on that.
  2. The team will cheer you and/or discuss with you the issue.
  3. Fork the project.
  4. Clone your forked project and create a git branch.
  5. Make the necessary code changes in as many commits as you want. The commit message should follow this convention:
:emoji: Short description #IssueID

Long description if needed.
  1. Create a pull request. After reviewing your changes and making any new commits if needed, the team will approve and merge it.

For a complete list of emoji description see this repository.

Code Guidelines

We follow the following standard guidelines with custom changes:

As the mono team says:

  • It is more important to be correct than to be fast.
  • It is more important to be maintainable than to be fast.
  • Fast code that is difficult to maintain is likely going to be looked down upon.

And don't miss The Zen of Python:

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Quality

We focus on code-quality to make ours and others life easier. For that reason:

  • ✔️ DO write documentation for any public type and field.
  • ✔️ DO write a test for all the possible code branches of your methods. Use a TDD approach.
  • ✔️ DO seek for 100% test coverage.
  • ✔️ DO seek for compiler warning free code.
  • ✔️ DO check the code with StyleCop for style issues.
  • ✔️ DO check the code with Gendarme for design issues.
  • ✔️ DO review the results of SonarQube in the Pull Request.
  • ✔️ DO make sure the CI pass.

Style Guidelines

Indentation

  • ✔️ DO use spaces with an indentation level of 4 spaces.
  • ❌ DO NOT use tabs.

New lines

  • ✔️ DO use Unix new lines: \n instead of Windows style \r\n. In general, Git will handle that for you.
  • ✔️ DO make sure there is an empty line at the end of the file. This ensure the latest line ends with the new line character and adding new lines after it won't show that line as changed in the diff.

Line length

  • ✔️ DO use a limit of 80 columns. If you need to wrap, move to the next line with one extra indentation level.
  • ✔️ DO put all the arguments in a new line if they don't fit.
  • ✔️ DO use local variables to make small conditions.
void Method(
    int a,
    string b,
    int c)
{
    OtherMethod(
        a,
        b,
        c);

    bool z = (a > 3) && (a < 5);
    bool w = b.StartsWith("hello");
    if (z && w) {
        Code();
    }
}

Layout

  • ✔️ DO define a type (class / struct / enum) per file.
  • ✔️ DO separate methods and properties with new lines.
  • ✔️ DO place the elements in this order: private fields, constructors, properties, methods, nested types. Place first static fields and order by visibility: public, protected, private.

Spacing rules

  • ❌ DO NOT leave any trailing spaces.
  • ❌ DO NOT use space before opening parenthesis calling methods or indexers, between the parenthesis and the arguments or between the generic types.
Method ( a );
array [ 10 ];
var list = new List <int> ();
  • ✔️ DO use the following convention:
Method(a);
array[10];
var list = new List<int>();
  • ✔️ DO use spaces and parenthesis for clarity in math operations:
int b = (a + (5 * 2)) / (3 + 3);
  • ✔️ DO indent case statements:
switch (a) {
    case 3:
        c = "hello";
        break;

    case 5:
        c = "world";
        break;

    default:
        throw new Exception();
}

Brace position

  • ✔️ DO put the opening brace on the same line for conditions, loops and try-catch.
if (a) {
    Code();
    Code();
} else if (b) {
    Code();
} else {
    Code();
}

try {
    Something();
} catch (ArgumentNullException ex) {
    Something();
} finally {
    Something();
}

for (int i = 0; i < 2; i++) {
    Something();
}
  • ✔️ DO use braces for one line conditions and loops. This improves readability and avoid having changed lines just to add the brace when it requires extra logic. The exception is for one line conditions for argument checking.
if (a) {
    Code();
}
  • ✔️ DO put the brace in a new line when defining the namespace, a type or a method.
namespace Program.Text
{
    public class Abc
    {
        public void MyMethod()
        {
        }
    }
}
  • ✔️ DO put the brace in the same line for properties and indexers.
public int Property {
    get {
        return value;
    }
}
  • ✔️ DO put each brace on a new line for empty methods.
void EmptyMethod()
{
}

Multiline comments

  • ✔️ DO use always double slash comments.
// Blah
// Blah again
// and another Blah

Properties

  • ❌ DO NOT use public variables under any circumstance.

  • ✔️ DO use static properties for constants.

  • ✔️ DO put the getter and setter in a new line for automatic or one line properties.

public int Property {
    get { return value; }
    set { x = value; }
}

public int Text {
    get;
    private set;
}

File headers

  • ✔️ DO put the license in the file header with this format:
//
// <FileName>.cs
//
// Author:
//       <AuthorName> <[email protected]>
//
// Copyright (c) <Year> <AuthorName>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.

Naming

  • ✔️ DO use always camel casing.
void Method(string myArgument)

class MyClass
{
    string myString;
    int veryImportantValue;
}
  • ❌ DO NOT use m_ or _ as prefixes for private instance members. The private visibility was created for that, really.

Keyword this

  • ❌ DO NOT use this if it's not needed.
  • ✔️ DO use this if the method has an argument with the same name.
class Foo
{
    int bar;

    public Foo(int bar)
    {
        this.bar = bar;
    }

    void Update(int newValue)
    {
       bar = newValue;
       Method();
    }

    public void Method()
    {
    }
}

Keyword var

  • ✔️ DO use the var on the left-hand side of an assignment when the type name is repeated on the right hand side:
var monkeyUUID = new NSUuid(uuid);
NSUuid something = RetrieveUUID();

Initializing instances

  • ✔️ DO use the C# syntax to initialize instances.
var x = new Foo {
    Label = "This",
    Color = Color.Red
};

string[] array = { "a", "b", "c" };
var array2 = new string[] { "d", "e", "f" };

var list = new List<string> {
    "hello",
    "world"
};

var dict = new Dictionary<string, int> {
    { "hello": 0 },
    { "world": 1 }
};

Redundant visibility

  • ❌ DO NOT use the private keyword to indicate internal fields since it's already the default visibility.

Usings

  • ✔️ DO put the using inside the namespace.

  • ✔️ DO include all the namespaces you are using.

  • ✔️ DO use the using statement for IDisposable types.

Built-in types

  • ✔️ DO use the built-in type alias instead of the class names.
int a = 5;
long b = 5;
string c = "hello";
string d = int.Parse("5");

Integers

  • ✔️ DO try to avoid unsigned integers in public method arguments and properties. Some .NET language doesn't support them.

Strings

  • ✔️ DO use the new string interpolation:
int a = 5;
string b = $"The result is {a}";
  • ✔️ DO use the StringBuilder class when creating strings with many operations.