Turing.jl: Style

[willtebbutt]

Please feel free to shut me down if this isn't a discussion we want to have right now, but there are a number of inconsistent / unusual conventions that we're following throughout the codebase. Given that we're about to embark on rather a lot of work, and there are a number of new people coming on board, it might be an opportune time to decide on some rules that we enforce (in a meticulous manner) in all new PRs, and apply retrospectively as we get around to it. We need a full style guide really, and I'm happy to provide suggestions on this front, but below are a few issues that I feel need to be addressed fairly urgently.

1. Firstly, there are currently two (long) function declaration styles used throughout the package:

foo(x) = begin
# code
end

and

function foo(x)
# code
end

I have a strong preference for the second one, as it is substantially more prevalent throughout other Julia packages and is IMHO substantially cleaner.

1. Short-style function declarations: we really should stick to the 92 character line-limits. So while

foo(x) = # code

seems fine to me provided that the entire line comes to under 92 characters, we should enforce that anything over 92 characters use the long-style format.

1. Multi-line function declarations: sometimes long-style functions declarations

function foo(x, y, z, ...) where {stuff}

will go over 92 characters. In this case, I've seen a few conventions, but I'm personally a fan of

function foo(
    arg1,
    arg2,
) where {stuff}
 # code
end

I'm not sure if we currently have a policy on this or not...

1. Comments in code:

function foo(x)

    # comment
    code

    # another comment
    some_more_code
end

as opposed to

function foo(x)
    # comment
    code
    # another comment
    some_more_code
end

seems reasonable to me.

1. (Disclaimer: this is entirely personal preference, and I am _totally_ happy for someone to tell me that this isn't going to happen) indentation: we're using 2-space indentation. I've seen this convention used in Flux.jl, but all of Base and the stdlib are written with 4 spaces, as are just about every other package in the eco-system. I would advocate enforcing 4 spaces everywhere.

The above basic suggestions are straightforward, and I really think that we need a more all-encompassing set of rules, but hopefully this is the start of a discussion on the matter.

[yebai]

@willtebbutt Thanks for raising this issue. I think it's important to stick to a set of style rules from now on. I'm happy to follow any style rules once a consensus is reached. We can check and enforce these rules during code review.

[mohamed82008]

Recent style guidelines of JuMP: http://www.juliaopt.org/JuMP.jl/latest/style.html. With the exception of their ! convention, the rest seem reasonable.

[willtebbutt]

What's there looks good. @omus is Invenia's style guide public?

[willtebbutt]

The basic Julia style guide is something we should be following anyway, but it's not as specific as we require to be honest.

[trappmartin]

I think this discussion is very important. It would probably be a good idea to develop a policy and include it in the repo so that contributors can easily follow the policy.

[willtebbutt]

Here's Invenia's style guide, which they have kindly allowed me to provide. It's fairly exhaustive, and I think it's the level of detail that we aught to be going for.
style_guide.txt

(It's a markdown file, not a text file, so bear that in mind when trying to view it)

[trappmartin]

@willtebbutt this looks like a very reasonable style guide. To which extent are we allowed to reuse parts of the style guide?

[willtebbutt]

We can just use it, but we should put a big thing at the top of the document that thanks Invenia for letting us use it. @yebai @xukai92 @mohamed82008 @wesselb what are your thoughts on the guide?

[willtebbutt]

This issue is superseded by #494.