Contributing Rust code to MaidSafe

We don't maintain a separate style guide but in general try to follow common good practice, write readable and idiomatic code and aim for full test coverage. In addition, this document lists a few decisions we've reached in discussions about specific topics.

Rust version

We currently use Rust stable 1.16.0.

Unwrap

Don't unwrap Options or Results, except possibly when:

1. locking a mutex,
2. spawning a thread,
3. joining a thread

or in other patterns where using them makes the code much simpler and it is obvious at first glance to the reader (even one unfamiliar with the code) that the value cannot be None/Err.

In these cases, as well as in tests, consider using the macros from the unwrap crate.

Threads

Generally avoid detached threads. Give child threads meaningful names.

This can easily be achieved by preferring to create child threads using maidsafe_utilities::thread::named().

• it returns a Joiner which helps to avoid detached threads
• it requires that the child thread is given a name

Rustfmt

Apply the latest rustfmt to new code before committing, using the default configuration or, if present, the repository's rustfmt.toml file.

Function ordering

In impls, always put public functions before private ones.

Clippy

If a crate has that feature, make sure your code does not produce any new errors when compiling with --features=clippy. If you don't agree with a Clippy lint, discuss it with the team before explicitly adding an #[allow(lint)] attribute.

For clippy, we currently use Clippy 0.0.120 and nightly installed by rustup install nightly-2017-03-16:

rustc --version
rustc 1.17.0-nightly (0aeb9c129 2017-03-15)

Note for Windows users: Due to a recent bug in rustup, you may get a missing dll error when trying to run cargo clippy. In this case, you can work around the issue by modifying your PATH environment variable:

setx PATH "%USERPROFILE%\.multirust\toolchains\nightly-2017-03-16-x86_64-pc-windows-gnu\bin;%PATH%"

Cargo

Use cargo-edit to update dependencies or keep the Cargo.toml in the formatting that cargo-edit uses.

Other crates

Adding new dependencies to MaidSafe crates in general should be discussed in the team first, except if other MaidSafe crates already have the same dependency. E.g. quick-error and unwrap are fine to use.

Git Commit Messages

The first line of the commit message should have the format <type>/<scope>: <subject>. For details see the Leaf project's guidelines.