Full YASGuide implementation

[ararslan]

Here are some (hopefully complete) to-dos to make the experimental YASGuide implementation complete, for whomever wishes to work on it. This is the style guide my company uses, so we'd likely adopt JuliaFormatter if it supported it. This guide has a significant amount of overlap with BlueStyle, so adding the functionality outlined below would also increase the ability to support other popular guides. (Indeed, all but a couple of these apply to both YAS and Blue.)

• Require ; to separate positional and keyword arguments
• Rewrite x |> f to f(x)
• Align line-broken arguments to the parent opening parenthesis (format_text errors for me with function arguments on multiple lines)
• Require explicit return for returned values in long form function definitions and do blocks
• Rewrite short form function definitions to long form if the line gets too long
• Expand and paren-wrap arithmetic in indexing expressions (x[i+1:end] -> x[(i + 1):end])
• Rewrite import X to using X
• Rewrite @Module.macro to Module.@macro
• Annotate unannotated fields in type definitions with ::Any
• Remove spaces around = in named tuple literals
• Rewrite function definitions inside of other function definitions to be lambdas

[domluna]

@ararslan which of these is preferable

1. fit as much on the same line

comp = [a * b + c for a = 1:10, # comment
        b = 11:20, c = 300:400]

2. break all lines if there if a comment

comp = [a * b + c for
        a = 1:10, # comment
        b = 11:20,
        c = 300:400]

[ararslan]

That's a good question, I don't think I've ever seen a comment in the middle of a comprehension. The YASGuide itself definitely doesn't have anything specific to say on this. I'd probably be inclined to prefer the latter just because I would find it visually odd to separate loops that way, but also having the dangling for on the first line feels weird. @jrevels, thoughts?

I guess a third option is

comp = [a * b + c
        for a in 1:10,  # comment
            b in 11:20,
            c in 300:400]

but that indentation feels unsatisfyingly arbitrary.

[jrevels]

Yeah, I don't think the YASGuide mandates anything here, but in my own code, I think I tend to prefer @ararslan's third option.

For complicated multiline comprehension bodies, I'll sometimes use begin...end blocks, e.g.:

comp = [begin
            x = a * b + c
            y = x^2 + 3x # comment 1
        end
        for a in 1:10,  # comment 2
            b in 11:20,
            c in 300:400]

I haven't thought too hard about this preference though 😁

[ararslan]

It's no longer possible to use begin/end in comprehensions as of 1.4, since x[begin] is a thing (mirrors x[end]). You can use let/end I think though.

[StefanKarpinski]

It's allowed in untyped comprehensions like this one, but not in typed comprehensions.

[ararslan]

Ah, gotcha.

[domluna]

I would find it visually odd to separate loops that way, but also having the dangling for on the first line feels weird

should this be formatted differently then?

https://github.com/beacon-biosignals/Onda.jl/blob/master/examples/tour.jl#L61-L62

[ararslan]

I'd say so, good catch 😄

[domluna]

@ararslan

Rewrite function definitions inside of other function definitions to be lambdas

can you give an example?

[domluna]

Rewrite import X to using X

@StefanKarpinski are there a cases where import would be preferred instead of using?

[StefanKarpinski]

If you want to add methods to the binding without qualification then import is required. So, suppose you have this:

module A
    export f
    function f end
end

Then this doesn't work:

julia> module B
           using ..A: f
           f() = 1
       end
ERROR: error in method definition: function A.f must be explicitly imported to be extended
Stacktrace:
 [1] top-level scope at none:0
 [2] top-level scope at REPL[2]:3

Whereas this does:

julia> module B
           import ..A: f
           f() = 1
       end
Main.B

I don't particularly like this distinction and argued against it pre-1.0, but there you have it. If, however, you use qualified names to extend imported functions then you can always use using:

julia> module B
           using ..A: A, f
           A.f() = 1
       end
WARNING: replacing module B.
Main.B

Note, however, that if you're explicitly listing the names to include, you have to list A itself or you won't be able to write A.f inside of B. So this whole thing is a bit of a mess.

[domluna]

hmmm ok, I was wondering whether I should make that conversion the default but it looks like it could break code in some cases

[StefanKarpinski]

There's definitely a transformation that could be done, but it's more annoying and non-local than one would want. The normalization that would be safe is this:

• using A replace by using A: names... with explicitly listed names from A that are used.
• import A replace by using A: A or drop it if A is never referenced
• import A: x
  • if x is not a function which is extended, replace by using A: x
  • if x is a function which is extended, replace by using A: A, x and qualify the reference to x in the method extension signature as A.x

So yeah, that's a very annoying and fussy normalization process just to unify on using. It's simpler if you go the other direction and transform using into import:

• using A replaced by import A: names... with explicitly listed names from A that are used.
• using A: x replaced by import A: x

I think that should never break code. And of course, you'd want to combine import statements that come from the same module. I do also think that it's good style to fully qualify extensions to imported methods just to be 100% clear that's what you're doing.

[ararslan]

hmmm ok, I was wondering whether I should make that conversion the default but it looks like it could break code in some cases

For the purposes of YASGuide compliance, import A could become using A: A, which is what we've been doing when we need that particular behavior. So that would be the most conservative change the formatter could make for compliance.