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()

[nickrobinson251]

Numbers

• Floating-point numbers should always include a leading and/or trailing zero (Almost already supported)

• For leading 0

julia> str = ".1";

julia> print(format_text(str))
0.1

• For trailing 0

julia> str = "2.";

julia> print(format_text(str))
2.0

• For Float32 (Float32 edge cases of leading/trailing 0 in floating points #286)

julia> str = "3.f0";

julia> print(format_text(str))
3.f0

Desired output is 3.0f0 like

julia> 3.f0
3.0f0

[nickrobinson251]

Ternary Operator

• Ternary operators ?: should generally only consume a single line

# Yes:
foobar = foo == 2 ? bar : baz

# No:
foobar = foo == 2 ?
    bar :
    baz

Currently supported for the case where it can fit on one line

julia> str = """
       foobar = foo == 2 ?
           bar :
           baz
       """;

julia> print(format_text(str))
foobar = foo == 2 ? bar : baz

But i think BlueStyle prefers if... else... if the whole thing cannot fit on one line e.g.

# Yes:
foobar = if some_big_long_thing * 10_000 == 2
    bar
else
    another_big_long_thing * 10^300 / this_things_here
end

# No:
foobar = some_big_long_thing * 10_000 == 2 ?
    bar :
    another_big_long_thing * 10^300 / this_things_here

whereas JuliaFormatter goes to:

julia> str = """
       foobar = some_big_long_thing * 10_000 == 2 ?
           bar :
           another_big_long_thing * 10^300 / this_things_here
       """;

julia> print(format_text(str))
foobar = some_big_long_thing * 10_000 == 2 ? bar :
    another_big_long_thing * 10^300 / this_things_here

---

• Do not chain multiple ternary operators. If chaining many conditions, consider using an if-elseif-else conditional

# Yes
foobar = if foo == 2
    bar
elseif foo == 3
    qux
else
    baz
end

# No
foobar = foo == 2 ? bar : foo == 3 ? qux : baz

[nickrobinson251]

For Loops

• For loops should always use in, never = or ∈. This also applies to list and generator comprehensions (Already supported)

julia> str = """
       for i = 1:10
           #...
       end

       [foo(x) for x ∈ xs]
       """;

julia> print(format_text(str, always_for_in=true))
for i in 1:10
    #...
end

[foo(x) for x in xs]

[nickrobinson251]

Comments

Before I write this bit out, @domluna can JuliaFormatter move or edit comments?
e.g. in this silly example, can it change from

looooooooong_variable = 10_000_000  # make this quite a big number so it takes up some space in the line

to

# make this quite a big number so it takes up some space in the line
looooooooong_variable = 10_000_000  

?

[domluna]

Comment

Before I write this bit out, @domluna can JuliaFormatter move or edit comments?
e.g. in this silly example, can it change from

looooooooong_variable = 10_000_000  # make this quite a big number so it takes up some space in the line

to

# make this quite a big number so it takes up some space in the line
looooooooong_variable = 10_000_000  

?

Right now it just indents and dedents comments

inline comments like these are represented as their own node type so it probably wouldn't be too difficult to do this, I'm guessing it would depend on how general or niche this transform is, meaning is this done in all situations or only a handful?

[nickrobinson251]

is this done in all situations or only a handful?

in cases where the inline comment would take the line length past the 92 char limit.

Here are the guidelines for comments:

• inline comments should be separated by at least two spaces from the expression and have a single space after the #.

---

• Only use inline comments if they fit within the line length limit

# Yes
# make this quite a big number so it takes up some space in the line
looooooooong_variable = 10_000_000  

# No
looooooooong_variable = 10_000_000  # make this quite a big number so it takes up some space in the line

---

• Non-inline comment should be above the content to which it refers

# Yes:
# Number of nodes to predict. Again, an issue with the workflow order. 
# Should be updated after data is fetched.
p = 1

# No:
p = 1  # Number of nodes to predict. Again, an issue with the workflow order. 
# Should be updated after data is fetched.

[domluna]

# Yes:
# Number of nodes to predict. Again, an issue with the workflow order. 
# Should be updated after data is fetched.
p = 1

# No:
p = 1  # Number of nodes to predict. Again, an issue with the workflow order. 
# Should be updated after data is fetched.

this case might be a pain to implement. I would be more comfortable leaving this up to the user.

[nickrobinson251]

this case might be a pain to implement. I would be more comfortable leaving this up to the user.

Yeah, I think that's fair enough. Let's leave this one out :)

[nickrobinson251]

By the way, the white-space rules for function definitions in BlueStyle allow quite a lot of flexibility.

In particular, it supports the idea you proposed here, Dom: jrevels/YASGuide#16 (comment))

Right now JuliaFormatter does this, which is consistent with BlueStyle

julia> str = """
       function long_name_of_function_because_i_am_writing_an_example(
           arg1, arg2, arg3, arg4, arg5, arg6,
       )
           # code
       end
       """;

julia> print(format_text(str))
function long_name_of_function_because_i_am_writing_an_example(
    arg1,
    arg2,
    arg3,
    arg4,
    arg5,
    arg6,
)
    # code
end

but the original code actually fit with in the line limit (once all the args were on that second line)
so BlueStyle would also allow you to leave the code as it was (in fact, that might be preferable), i.e.

julia> print(format_test(str; style=BlueStyle())  # hypothetical
function long_name_of_function_because_i_am_writing_an_example(
    arg1, arg2, arg3, arg4, arg5, arg6,
)
    # code
end

But then have the current behaviour if it'd go beyond the line limits to have all the args on one line e.g.
this current behaviour is still great

julia> str = """
       function long_name_of_function_because_i_am_writing_an_example(
           arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9, arg10, arg11, arg12
       )
           # code
       end
       """;

julia> print(format_text(str))
function long_name_of_function_because_i_am_writing_an_example(
    arg1,
    arg2,
    arg3,
    arg4,
    arg5,
    arg6,
    arg7,
    arg8,
    arg9,
    arg10,
    arg11,
    arg12,
)
    # code
end

[domluna]

@nickrobinson251 which ones are higher priority than others? I'm thinking it may be better to implement these incrementally instead of doing 1 big PR

[nickrobinson251]

I'm thinking it may be better to implement these incrementally instead of doing 1 big PR

Yeah, that sounds better to me too.

which ones are higher priority than others?

I'd say top three priorities, in order, are

1. Assignments using function calls should have the first open bracket on the same line as the assignment operator (the one discussed above)
2. When using long-form functions always use the return keyword (but don't also add return to do-blocks)
3. Separate keyword arguments from positional arguments with a semicolon

for context:
1 and 2 are high priority based on the changes the Formatter currently makes to code that follows BlueStyle (i.e. we want to remove cases where the Formatter makes style "worse" according to BlueStyle)

• for 1, there's no setting of the formatter that doesn't get this "wrong"
• for 2, there's no setting of the formatter that gets the return in fuction "right" without also getting something "wrong" (do-blocks)

3 is high priority based on this being the most common style reminder made in code-reviews on codebases following BlueStyle (at least the most common that the Formatter doesn't already help with, and based on my memory of code reviews), so first on the list of feature that'd be nice to have, i think.

[domluna]

Assignments using function calls should have the first open bracket on the same line as the assignment operator (the one discussed above)

@nickrobinson251 does this also apply to short function definitions?

[nickrobinson251]

Since we have "Only use short-form function definitions when they fit on a single line", this should never come up for short-form functions (i.e. if we're wondering how to put a short-form function over multiple lines, we should instead make it a long-form function)

[nickrobinson251]

Using v0.9.1, this code gets changed to something not quite right (from https://github.com/invenia/LibPQ.jl/pull/197/files/0e908dfb097273fe1eb87050c4f0d99d071232ed#r494597229)

julia> str = """
           Dict(
               "options" => join(
                   imap(Iterators.filter(keep_option, connection_options)) do (k, v)
                       "-c k=(show_option(v))"
                   end,
                   " ",
               ),
           )
           """;

julia> println(format_text(str, BlueStyle()))
Dict(
    "options" => join(imap(Iterators.filter(keep_option, connection_options)) do (k, v)
        "-c k=(show_option(v))"
    end, " "),
)

Since in the changed version the join call breaks this rule

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.

Instead, the ), should remain on its own line. (At least, i think that's what @iamed2 says should happen?)

[domluna]

Using v0.9.1, this code gets changed to something not quite right (from https://github.com/invenia/LibPQ.jl/pull/197/files/0e908dfb097273fe1eb87050c4f0d99d071232ed#r494597229)

julia> str = """
           Dict(
               "options" => join(
                   imap(Iterators.filter(keep_option, connection_options)) do (k, v)
                       "-c k=(show_option(v))"
                   end,
                   " ",
               ),
           )
           """;

julia> println(format_text(str, BlueStyle()))
Dict(
    "options" => join(imap(Iterators.filter(keep_option, connection_options)) do (k, v)
        "-c k=(show_option(v))"
    end, " "),
)

Since in the changed version the join call breaks this rule

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.

Instead, the ), should remain on its own line. (At least, i think that's what @iamed2 says should happen?)

So in an attempt to generalize this is it implied that if an argument spans multiple lines (the do block in this case), the args should spread automatically over multiple lines, regardless of margin?

[nickrobinson251]

i'mma tag in @iamed2 on this one ^

[iamed2]

So in an attempt to generalize this is it implied that if an argument spans multiple lines (the do block in this case), the args should spread automatically over multiple lines, regardless of margin?

Yep that's right

[domluna]

woops apparently GH doesn't distinguish between issues and comments in issues

[domluna]

746c456 disallows chained ternary

[domluna]

94cb799 implements return nothing over return

[domluna]

After a function definition, and before an end statement do not include a blank line.

What about in all cases except for modules?

#309

[nickrobinson251]

What about in all cases except for modules?

#309

Sounds perfect 🎊

[nickrobinson251]

This doesn't see quite right:

given this code that goes over the line limit

    df[:, :some_column] = [some_big_function_name(blahhh) for (fooooo, blahhh) in my_long_list_of_vars]

Ideally it'd be changed to

    df[:, :some_column] = [
        some_big_function_name(blahhh) for (fooooo, blahhh) in my_long_list_of_vars
    ]

But the BlueStyle breaks up the indexed on the left-hand side instead:

(using JuliaFormatter v0.10)

julia> str = """
           df[:, :some_column] = [some_big_function_name(blahhh) for (fooooo, blahhh) in my_long_list_of_vars]
       """;

julia> println(format_text(str, BlueStyle()))
df[
    :, :some_column
] = [some_big_function_name(blahhh) for (fooooo, blahhh) in my_long_list_of_vars]


julia> println(format_text(str))  # DefaultStyle, for comparison
df[:, :some_column] =
    [some_big_function_name(blahhh) for (fooooo, blahhh) in my_long_list_of_vars]

---

I think we just never want to break-up the left-hand side of the assignment operator =

[domluna]

makes sense, that's what YASStyle does we can just dispatch that 1

fixed

[nickrobinson251]

I'm trying out the formatter (v0.10.1) on a few repos, and it's pretty amazing. Great work!

Here's one case where i can't help but feel it's made the code less clean/clear... not sure what we can do about it

julia> str = """
function f()
    for i in 1:n
        @inbounds mul!(
            reshape(view(C, :, i), eye_n, k),
            reshape(view(B, :, i), eye_n, l),
            transpose(A),
        )
    end
end
""";

julia> println(format_text(str, BlueStyle()))
function f()
    for i in 1:n
        @inbounds mul!(
            reshape(view(C, :, i), eye_n, k), reshape(view(B, :, i), eye_n, l), transpose(
                A
            )
        )
    end
end

---

I wonder if the rule "if the function call doesn't fit on one line, then try to fit all the args on the next line, otherwise put them on a line each" that we use for function definitions should only apply to definitions, not also to callsites?
i.e. the rule that says

function long_name_of_function_because_i_am_writing_an_example(
    arg1, arg2, arg3, arg4, arg5, arg6
)
    # code
 end

is allowed/good should not be applied to the call, i.e. we'd still want

return_var = long_name_of_function_because_i_am_writing_an_example(
    arg1,
    arg2,
    arg3, 
    arg4,
    arg5,
    arg6,
)

Or at least, if it's written in this arg-on-multiple-lines way, the formatter shouldn't format it into the args-on-a-single-line (unless the whole function call fits on a single line i.e. f(args) fit on the same line)

What does @iamed2 think?

[domluna]

That actually looks like a bug tbh

UPDATE: resolved as of v0.10.2