DOC: write style guide

[sglyon]

We need a style guide so that contributors know what conventions they should follow. We should be sure to include at least:

• [x] spaces after all commas (in indexing expressions, tuples, function declarations, function calls)
• [ ] Docstring conventions
• [x] No trailing whitespace
• [x] 4 space indentation (no tabs, not 2 or 8 spaces)
• [ ] Either 80 or 92 column limit per line (I've always done 80 -- official Julia contributor guide recommends 92. We need to make a decision here. Any comments?)
• [ ] All keyword arguments must be typed
• [x] Function arguments that go onto new lines should be indented all the way to the column where the first function argument begins (note that despite what I have in the example below, function arguments should be put on the same line unless they will violate the max column rule):

# bad
function foo(x::Int,
    y::Float64)
    x + y
end

# good
function foo(x::Int,
             y::Float64
    x + y
end

• [ ] All new functionality must be tested before it will be merged
• [x] Types and module names should be UpperCamelCase
• [x] Function names should be lowercase, words separated by underscore (_) as needed
• [x] Functions should be separated by ecactly 1 line of whitespace
• [ ] One line functions should be one line:

# bad
function foo(x::Int, y::Float64)
    x + y
end

# good
foo(x::Int, y::Float64) = x + y

• [ ] If one line function exceeds max column limit on single line, use the trailing = and 4 space rule:

Basis(p::AnyParam, ps::AnyParam...) =
    Basis(Basis(p), Basis[Basis(p) for p in ps]...)::Basis{length(ps) + 1}

• [x] No whitespace around default function arguments

# bad
foo(x::Int, y::Float64 = 1.0) = x + y

# good
foo(x::Int, y::Float64=1.0) = x + y

• [ ] Make sure code runs on latest release and dev version of Julia (utilize Compat.jl as necessary).

There are probably others. Please comment and let me know if I left anything out. Or feel free to propose alternatives to what I have here.

[sglyon]

Also need:

• [x] New line at the end of a file
• [ ] Decision regarding where import and using statements go.
• [ ] Decision regarding use of import or Module.function syntax for adding a new method

[sglyon]

Chase doesn't like

foo(x, y) = 
    this_is_too_long_to_fit_on_one_line(bar, baz, bing, bog, boop)

He prefers

function foo(x, y)
    this_is_too_long_to_fit_on_one_line(bar, baz, bing, bog, boop)
end

[ZacCranko]

I'm happy with the first one, since it is a lot more compact than

@inline function foo(x, y)
    this_is_too_long_to_fit_on_one_line(bar, baz, bing, bog, boop)
end

and also extremely common in Base.jl

[Ken-B]

In case you haven't seen it yet, John Myles White has a quite extensive style guide for Julia: https://github.com/johnmyleswhite/Style.jl

You might take some inspiration from it (I tend to use almost all). He is an 80 column wide guy, though ;-)

[sglyon]

Thanks for reminding me about this. I think my guidelines will be pretty similar to John's.

I've got about 1/3-1/2 of it written up here

[Nosferican]

Regarding where and how to use using and import. My preferred method is to have them at the top of every module, explicit, and descriptive.

"""
    GreatPkg
This is an example module.
"""
module GreatPkg

using StatsBase: ConvergenceException, StatisticalModel, RegressionModel, 
                 FrequencyWeights, model_response
using DataFrames: DataFrame

import StatsBase: fit!, deviance, loglikelihood, coef, informationmatrix, isfitted,
                  islinear, vcov

end

A few considerations:

• Is explicit on what you are using and what you are extending
• All dependencies and what you are using from each is explicit
• Everything is in one place (no code-hunting)
• Namespace is not clutter and doesn't let you to use namespace in a way that can be confusing

[sglyon]

Great suggestions. That's my preferred approach also.