Implement BlueStyle

[nickrobinson251]

This issue is to organise and track efforts to implement BlueStyle as a Custom Style. Similar to how YASGuide is now available in JuliaFormatter via YASStyle. (see issue #198 and PRs #214, #217).

I think the first step is to come up with a list of cases where BlueStyle recommends a style change that is currently not available via DefaultStyle or YASStyle...

TO DOs (see comment below for details/examples):

• Module Imports
  • Imports at top of file (see also send using and import statements to the top #284)
  • Order imports alphabetically (see also Sort imports #257)
  • One module import per line
  • Prefer using over import
• Global Variables (not possible?)
• Function Naming (not possible)
• module exports (see Add preferences on function exports for BlueStyle #358)
• Method Definitions
  • Only use short-form function definitions when they fit on a single line
  • When using long-form functions always use the return keyword (but not in do blocks) (second highest priority) (BlueStyle - implement top 3 issues #295)
  • use return nothing rather than bare return (94cb799)
• Keyword Arguments
  • No whitespace in keyword arguments
  • Separate keyword arguments from positional arguments with a ; semicolon (third highest priority) (BlueStyle - implement top 3 issues #295)
• Whitespace
  • Avoid extraneous whitespace immediately inside brackets
  • Avoid extraneous whitespace immediately before a comma or semicolon
  • Avoid whitespace around : in ranges, add brackets to clarify
  • Avoid whitespace for alignment
  • Surround most binary operators with a single space
    • except ^
    • except // (Give // the same binaryop whitespace exception as ^ #288)
  • Avoid using whitespace between unary operands and the expression
  • Avoid extraneous empty lines
  • Function calls which cannot fit on a single line within the line limit should be broken up such that... (see below)
  • Function calls which cannot fit on a single line can allow all arguments on a second line if they fit within the line limit (see Implement BlueStyle #283 (comment), BlueStyle - implement top 3 issues #295)
  • Assignments using expanded notation for arrays or tuples should have the first open bracket on the same line assignment operator
  • Assignments using function calls should have the first open bracket on the same line as the assignment operator (highest priority, since it is much more common than other things that need to be implemented) (BlueStyle - implement top 3 issues #295)
  • Triple-quotes and triple-backticks written over multiple lines should be indented. The opening quotes should be on the same line as the assignment operator.
  • Blank lines between multi-line block (ending end)
    • Blank lines before return (pending Simplify some current guidance to "have a blank line between multi-line blocks"? JuliaDiff/BlueStyle#61)
• NamedTuples
  • The = character in NamedTuples should be spaced as in keyword arguments (i.e. like x=1, no spaces)
  • Empty NamedTuple written NamedTuple() not (;) (also see related issue JuliaFormatter changes empty NamedTuple (;) to empty Tuple () #285)
    • No leading ; (but pending Relax opinion on use of ; in NamedTuples? JuliaDiff/BlueStyle#62)
• Numbers
  • Float64 numbers should always include a leading and/or trailing zero
  • Float32 numbers should always include a leading and/or trailing zero (see Float32 edge cases of leading/trailing 0 in floating points #286)
• Ternary Operator
  • limit to one line (Conditional to if option #308)
  • do not chain (746c456)
• Short-circuit operators for control-flow
  • only on one line? (...pending Short-circuit logic used as control flow should only be used on a single line JuliaDiff/BlueStyle#72)
• For loops
  • For loops should always use in, never = or ∈.
• Type annotation (not possible for BlueStyle advice)
• Package version specifications (not possible)
• Comments
  • inline comments separated by at least two spaces from the expression and have space after #.
  • Only use inline comments if they fit within the line length limit (see also Imposing margin on comments #197)

Still to look into:

• Formatting docstrings

Could maybe also look into, but leaving these for now:

• Testsets formatting
• Test Comparisons

---

Going through this i realise that BlueStyle has a lot of things that cannot be automated, and that is fine. I think the intended use case for the formatter is an environment where collaborators know what style is intended and attempt to follow it, but don't have to sweat the details and don't have to rely on code review to fix whitespace style issues. I think this also means that its much more important that the formatter doesn't make "good" style into "bad" style, than it is to make all "bad" cases "good" (and all cases wouldn't be realistic anyway).

[nickrobinson251]

Module imports

• Module imports should occur at the top of the file or right after a module declaration

---

• one import per line

# Yes:
using A
using B

# No:
using A, B

---

• order imports alphabetically

# Yes:
using A
using B

# No:
using B
using A

---

• Prefer using over import(this is partially supported already)

# Yes:
using Example

Example.hello(x::Monster) = "Aargh! It's a Monster!"
Base.isreal(x::Ghost) = false

# No:
import Base: isreal
import Example: hello

hello(x::Monster) = "Aargh! It's a Monster!"
isreal(x::Ghost) = false

By partially supported I mean:

julia> str = """
       import Example: hello
       import Foo
       """;

julia> print(format_text(str, import_to_using=true))
import Example: hello  # <-- for BlueStyle should be `using Example: hello`, even though this can break code (see below)
using Foo: Foo

• I don't think we do the full code re-write for this example, but we can do import Example: hello - > using Example: hello.
• This one's still a bit complicated in the sense that changing import Example: hello to using Example: hello can break code...
  • with using Example: hello, the code hello(x::Monster) = "Aargh!" no longer successfully adds a method;
  • andExample.hello also wouldn't work, unless the code was changed to using Example or using Example: Example, hello.

But I think that's fine for following BlueStyle, since the purpose of this rule is "to ensure that extension of a function is always explicit and on purpose", so we'd want CI to fail in this case.

(I also think this is fine because I see JuliaFormatter as a great tool for "fixing up" code to follow the style guide you intended -- but realistically the code has to be written with some mind to that style in the first place -- not to entirely rewrite any possible given code (however far it deviates from the style guide) to have then be exactly as if rewritten by someone following the guide. If that makes sense....)

[nickrobinson251]

Method definitions

• Only use short-form function definitions when they fit on a single line (already supported)

julia> str = """
       foo(x::Int64) = abs(x) + 3

       foobar(array_data::AbstractArray{T}, item::T) where {T<:Int64} = T[
           abs(x) * abs(item) + 3 for x in array_data
       ]

       foobar(
           array_data::AbstractArray{T},
           item::T,
       ) where {T<:Int64} = T[abs(x) * abs(item) + 3 for x in array_data]
       """;

julia> print(format_text(str; short_to_long_function_def=true))
foo(x::Int64) = abs(x) + 3

function foobar(array_data::AbstractArray{T}, item::T) where {T<:Int64}
    T[abs(x) * abs(item) + 3 for x in array_data]
end

function foobar(array_data::AbstractArray{T}, item::T) where {T<:Int64}
    T[abs(x) * abs(item) + 3 for x in array_data]
end

---

• When using long-form functions always use the return keyword (partially supported?)

julia> str = """
       function Foo(x, y)
           new(x, y)
       end
       """;

julia> print(format_text(str; always_use_return=true))
function Foo(x, y)
    return new(x, y)
end

• "partially supported" because always_use_return affects do blocks, which BlueStyle doesn't want.
  • I think @ericphanson also requested excluding do-blocks from this this as an option
• also gets some edge-cases wrong Unnecessary return added setting always_use_return = true. #233

---

• Use return nothing instead of bare return

---

• Functions definitions with parameter lines which exceed 92 characters should separate each parameter by a newline and indent by one-level (already supported)

[nickrobinson251]

Keyword arguments

• No whitespace in keyword arguments (already supported)

julia> str = """
       xy = foo(x; y = 3)
       ab = foo(; a= 1, b= 2)
       """;

julia> print(format_text(str; whitespace_in_kwargs=false))
xy = foo(x; y=3)
ab = foo(; a=1, b=2)

---

• Always separate your keyword arguments from your positional arguments with a semicolon (I think YASStyle also prefers this Full YASGuide implementation #198)
  • xy = foo(x, y=3) should become xy = foo(x; y=3)
  • ab = foo(a=1, b=2) could become ab = foo(; a=1, b=2) (or i think we'd be fine if it was left as ab = foo(a=1, b=2)?)
  • ab = foo(; a=1, b=2) should be left as ab = foo(; a=1, b=2)

[nickrobinson251]

WhiteSpace

• Avoid extraneous whitespace immediately inside parentheses, square brackets or braces

julia> str = """
       spam( Ham{ T }( ), [ eggs ] )
       """;

julia> print(format_text(str))
spam(Ham{T}(), [eggs])

---

• Avoid extraneous whitespace immediately before a comma or semicolon (already supported I think?)

julia> str = """
       @show(x, y); x , y = y ;
       """;

julia> print(format_text(str))
@show(x, y);
x, y = y;

---

• Avoid whitespace around : in ranges. Use brackets to clarify expressions on either side. (already supported -- and i'm very impressed by this one)

julia> str = """
       ham[1: 9]
       ham[9 : -3: 1]
       ham[lower : upper - 1]
       ham[lower + offset:upper + offset]
       """;

julia> print(format_text(str; whitespace_ops_in_indices=true))
ham[1:9]
ham[9:-3:1]
ham[lower:(upper - 1)]
ham[(lower + offset):(upper + offset)]

---

• Avoid using more than one space around an assignment (or other) operator to align it with another

julia> str = """
       x             =  1
       y             =  2
       long_variable = 30
       """;

julia> print(format_text(str))
x = 1
y = 2
long_variable = 30

---

• Surround most binary operators with a single space on either side, excluding , :,^ and //) (Almost supported already)

julia> str = """
       i=j+1
       submitted +=1
       x^2<y
       x->x>1
       3!=2
       1 : 2
       1//2
       """;

julia> print(format_text(str))
i = j + 1
submitted += 1
x^2 < y  # <-- Nice!
x -> x > 1
3 != 2
1:2
1 // 2  # <-- BlueStyle would prefer 1//2 here, i think

If we want // to be treated like ^ i think (maybe?) we'd want to include Tokens.FWDFWD_SLASH like Tokens.CIRCUMFLEX_ACCENT is in p_binaryopcall

[nickrobinson251]

Whitespace (continued)

• Avoid using whitespace between unary operands and the expression. (Already supported)
  • Here's what BlueStyle says:

     # Yes:
     -1
     [1 0 -1]
    
     # No:
     - 1
     [1 0 - 1]  # Note: evaluates to `[1 -1]`
    

  • Here's what JuliaFormatter does:

    julia> str = """
       - 1
       [- 1 0 - 1]
       [-1 0  -1]
       """;
    
    julia> print(format_text(str))
    -1
    [-1 2 - 1]  
    [-1 2 -1]

    • I think maybe both are right here. i.e. if following BlueStyle, you should never write [- 1 2 - 1] (instead write [-1 1]). But if you do write this, you cannot expect the Formatter to correct you, because the Formatter doesn't do arithmetic.

---

• Avoid extraneous empty lines. (Already supported)

julia> str = """
       domath(x::Number) = x + 5
       domath(x::Int) = x + 10



       function domath(x::String)
           return "A string is a one-dimensional extended object postulated in string theory."
       end


       dophilosophy() = "Why?"
       """;

julia> print(format_text(str; remove_extra_newlines=true))
domath(x::Number) = x + 5
domath(x::Int) = x + 10

function domath(x::String)
    return "A string is a one-dimensional extended object postulated in string theory."
end

dophilosophy() = "Why?"

---

• Function calls which cannot fit on a single line within the line limit should be broken up such that the lines containing the opening and closing brackets are indented to the same level while the parameters of the function are indented one level further. In most cases the arguments and/or keywords should each be placed on separate lines. (Already supported 💥)

julia> str = """
       f(
           a,
           b,
       )
       constraint = conic_form!(SOCElemConstraint(temp2 + temp3,
                                                  temp2 - temp3, 2 * temp1),
                                unique_conic_forms)
       """;

julia> print(format_text(str))
f(a, b)
constraint = conic_form!(
    SOCElemConstraint(temp2 + temp3, temp2 - temp3, 2 * temp1),
    unique_conic_forms,
)

julia> str = """
       f(
           a,
           b,
       )
       constraint = conic_form!(SOCElemConstraint(temp2 + temp3,
                                                  temp2 - temp3, 2 * temp1, "other reallllllly long arg"),
                                unique_conic_forms)
       """;

julia> print(format_text(str))
f(a, b)
constraint = conic_form!(
    SOCElemConstraint(
        temp2 + temp3,
        temp2 - temp3,
        2 * temp1,
        "other reallllllly long arg",
    ),
    unique_conic_forms,
)

(^ I'm so impressed by this)

[nickrobinson251]

Whitespace (continued again)

---

• Assignments using expanded notation for arrays or tuples, or function calls should have the first open bracket on the same line assignment operator and the closing bracket should match the indentation level of the assignment. Alternatively you can perform assignments on a single line when they are short. (Almost supported)

  • Works for arrays or tuples

  julia> str = """
         arr =
         [
             1,
             2,
         3,
     ]
     arr =
     [
         1 2 3
     ]
     arr = [
         1
         2
         3
         ]
     tup = (
         1, 2, 3
     )
     """;
  
  julia> print(format_text(str))
  arr = [1, 2, 3]
  arr = [1 2 3]
  arr = [
      1
      2
      3
  ]
  tup = (1, 2, 3)

  • Doesn't do the right thing for functions?

  julia> str = """
         some_big_long_variable_that_takes_up_most_of_the_line_but_still_leaves_room_for_f = f(
             "argument doesn't fit on that first line", 2
         )
         """;  # <-- BlueStyle thinks this is preferable, with `= f(` on that first line; don't change anything
  
  julia> print(format_text(str))
  some_big_long_variable_that_takes_up_most_of_the_line_but_still_leaves_room_for_f =
      f("argument doesn't fit on that first line", 2)

  julia> str = """
         quite_long_variable_that_takes_up_space = f(
             "argument doesn't fit on that first line because now it's longer", 2
         )
         """;  # <-- BlueStyle thinks this is preferable, with `= f(` on that first line; don't change anything
  
  julia> print(format_text(str))
  quite_long_variable_that_takes_up_space =
      f("argument doesn't fit on that first line because now it's longer", 2)

[domluna]

julia> str = """
quite_long_variable_that_takes_up_space = f(
"argument doesn't fit on that first line because now it's longer", 2
)
"""; # <-- BlueStyle thinks this is preferable, with = f( on that first line; don't change anything

julia> print(format_text(str))
quite_long_variable_that_takes_up_space =
f("argument doesn't fit on that first line because now it's longer", 2)

First it places the RHS on the next line and if that's not gonna it lifts the function call f( to back up and the arguments each take up 1 line.

quite_long_variable_that_takes_up_space = f(
    "argument doesn't fit on that first line because now it's longer",
    2,
)

[nickrobinson251]

yah, either of these would be okay:

quite_long_variable_that_takes_up_space = f(
    "argument doesn't fit on that first line because now it's longer", 2
)

quite_long_variable_that_takes_up_space = f(
    "argument doesn't fit on that first line because now it's longer",
    2,
)

(maybe the second one is preferable, but crucially: the = f( being on the first line, then next lines indented once, and closing bracket on own line)

Is there a way to get that result already (I couldn't find one), or is it something we'd need to add for BlueStyle?

Running format_text (with no other settings) on

quite_long_variable_that_takes_up_space = f(
    "argument doesn't fit on that first line because now it's longer",
    2,
)

currently alters it and returns

quite_long_variable_that_takes_up_space =
    f("argument doesn't fit on that first line because now it's longer", 2)

[domluna]

It would probably be BlueStyle specific since I don't think it would be suitable as an option (seems it would be confusing). Doing it the way you mentioned is actually simpler from the formatter's point of view so that's a silver lining.

[nickrobinson251]

Whiespace (continued again, again)

• Always include the trailing comma when working with expanded arrays, tuples or functions notation (already supported)

julia> str = """
       arr1 = [
           1,
           2,
       ]
       arr2 = [
           "realllllllllllllllllllllllllllllly long one",
           "realllllllllllllllllllllllllllllly long two"
       ]
       tup = (
           1,
       )
       """;

julia> print(format_text(str))
arr1 = [1, 2]
arr2 = [
    "realllllllllllllllllllllllllllllly long one",
    "realllllllllllllllllllllllllllllly long two",
]
tup = (1,)

---

• Triple-quotes... idented and, if being assigned, starting on the same line as the =

# Yes:
str2 = """
         hello
    world!
    """

# No:
str2 = """
    hello
world!
"""

str2 = 
    """
         hello
    world!
    """

---

• Use blank-lines to separate different multi-line blocks.
  • TODO: I think this needs translating. Does it just mean "have a blank line after end"?
  • If so, then this later rule is just a special case of this one: "Use line breaks between control flow statements and returns." (assuming "control flow" here means only while.. end and if... end statements, which it seems to be, based on the example given).
  • I'd rather go with a sipler rule, e.g. "Add a blank line between multi-line blocks". But i'll move that discussion to Simplify some current guidance to "have a blank line between multi-line blocks"? JuliaDiff/BlueStyle#61

---

• After a function definition, and before an end statement do not include a blank line.
  • This is not currently support, as far as i can tell

julia> str = """
       function foo(bar::Int64, baz::Int64)

           return bar + baz
       end

       function foo(bar::In64, baz::Int64)
           return bar + baz

       end
       """;

julia> print(format_text(str; remove_extra_newlines=true))
function foo(bar::Int64, baz::Int64)

    return bar + baz
end

function foo(bar::In64, baz::Int64)
    return bar + baz

end

should both become:

function foo(bar::In64, baz::Int64)
    return bar + baz
end

[nickrobinson251]

NamedTuples

• The = character in NamedTuples should be spaced as in keyword arguments. No space should be put between the name and its value.

julia> str = """
       xy = (x = 1, y = 2)
       """;

julia> print(format_text(str, whitespace_in_kwargs=false))
xy = (x=1, y=2)

---

• NamedTuples should not be prefixed with ; at the start
  • TODO: Really? I write a lot of code in codebases that follow BlueStyle and I never knew this, and no one ever corrected me... opened an issue about it on BlueStyle Relax opinion on use of ; in NamedTuples? JuliaDiff/BlueStyle#62

julia> str = """
       xy = (; x = 1, y = 2)
       """;

julia> print(format_text(str, whitespace_in_kwargs=false))
xy = (; x=1, y=2)  # <-- should be `xy = (x=1, y=2)`, under current guidance, apparently

---

• The empty NamedTuple should be written NamedTuple() not (;)
  • Currently a bug in JuliaFormatter? JuliaFormatter changes empty NamedTuple (;) to empty Tuple () #285

  julia> str = """
         nt = (;)
         """;
  
  julia> print(format_text(str))
  nt = ()

  • Desired behaviour when using BlueStyle is:

  julia> str = """
         nt = (;)
         """;
  
  julia> print(format_text(str))
  nt = NamedTuple()