JuliaDiff / JuliaDiff/BlueStyle

Simplify some current guidance to "have a blank line between multi-line blocks"?

Open
#61 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
No language data
Stars
519
Forks
34
PR merge metrics
No merged PRs in 30d

Description

Noticed when writing up https://github.com/domluna/JuliaFormatter.jl/issues/283 (see https://github.com/domluna/JuliaFormatter.jl/issues/283#issuecomment-687795763, related to #7), but better to discuss here :)

We currently have two rules:

  • Use blank-lines to separate different multi-line blocks.
  • Use line breaks between control flow statements and returns.

i wasn't sure how to translate the first one into a rule for a Formatter to follow, unless it just mean "have a blank line after end". If it can be translated to that, then the second one is just a special-case (assuming "control flow" here means only while.. end and if... end statements, which it seems to be, based on the example given).

I suggest we simplify these two rules in one. Below are some options for the new rule:


Option 1:
  • Add a blank line after end in multi-line blocks
# Yes:
if foo
    println("Hi")
end

for i in 1:10
    println(i)
end

# No:
if foo
    println("Hi")
end
for i in 1:10
    println(i)
end
# Yes:
function foo(bar; verbose=false)
    if verbose
        println("baz")
    end

    return bar
end

# No:
function foo(bar; verbose=false)
    if verbose
        println("baz")
    end
    return bar
end
  • Note that in this second example, the No case is currently listed as OK.

Option 2
  • Add a blank line between multiple multi-line blocks
# Yes:
if foo
    println("Hi")
end

for i in 1:10
    println(i)
end

# No:
if foo
    println("Hi")
end
for i in 1:10
    println(i)
end
  • Note we now longer give an opinion on the second example above (the blank line after end / before return)

Option 3
  • Stop giving guidance on this

For what it is worth, i'd happily go with Option 3. In practice, i'm happy enough writing code that follows Option 2, but Option 1 seems a little too fussy to me.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read this issue alongside JuliaFormatter.jl #283, its linked comment, and #7 to understand the current guidance and examples. Since no file or test is named, first locate the style-guide text, then document the agreed rule and update its examples once the open options have a decision.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.