Convention about empty lines

[KalitaAlexey]

Hi everybody.

It looks like there is no any convention about empty lines.

I like to separate all function with one empty line.

fn foo() {}

fn bar() {}

I like to separate Control Flow Statements with one empty line.

fn foo(x: i32) -> i32 {
    let result = calculate(x);

    if result > 0 {
        result
    } else {
        0
    }
}

I like to separate blocks with one empty line.

fn foo() {
    {
        do_something();
        do_something_else();
    }

    {
        do_something_different();
        do_something_completely_different();
    }
}

I like to separate unrelated pieces with one empty line.

fn foo() {
    let mut x = create_x();
    x.do();
    x.do_something_else();

    let mut y = create_y();
    y.do();
    y.do_something_else();
}

I think we should have some convention about it.

Thanks,
Alexey

[gsingh93]

I think we should only define a convention for top level statements inside modules, i.e. one line between functions, struct definitions, impls, etc. I also think we should require the newline between method declarations inside impls. Of course, top level statements like use and extern would be grouped together (I think another issue addresses how to do this grouping). I'm not sure if this rule should apply to traits, or at least to traits with methods that don't have a body.

I don't think we should have any other requirements, and leave how to use newlines inside blocks and between control flow statements up to the user.

[nrc]

I have been somewhat reluctant to address this in rustfmt, where we treat newlines as significant whitespace and preserve it in the same way as comments. The reason for this is that People often use newline semantically - no lines between related statements, a blank line between separate groups of statements, multiple blank lines to enforce an even greater separation. Likewise, between items at module scope, if there are multiple single line, related functions there might be no newlines. Mostly functions are separated by one line, sometimes grouped using multiple lines.

Furthermore, it is really easy to fix manually - you just delete them, its not like you have to re-lay out code.

There seem to be some cases we can safely forbid, e.g., blank lines at the start of end of a block.

For other uses I see a few options:

1. continue to do preserve all newlines
2. preserve 0, 1, or 2 blank lines, e.g., a 5 line gap would be reduced to 2.
3. preserve 0 or 1 blank lines, e.g., a 5 line gap would be reduced to 1.
4. enforce 1 line between all items and do preserve function bodies (or reduce multiple lines to 1 inside function bodies).

I prefer 1 or 3 - I think 4 is too strict, and 2 is unnecessary.

[KalitaAlexey]

@nrc,
I like forbidding of blank lines at both the start and the end of a block.

I am up to 3 variant.

[joshtriplett]

On February 1, 2017 10:28:04 AM GMT+01:00, Nick Cameron ***@***.***> wrote: I have been somewhat reluctant to address this in rustfmt, where we treat newlines as significant whitespace and preserve it in the same way as comments. The reason for this is that People often use newline semantically - no lines between related statements, a blank line between separate groups of statements, multiple blank lines to enforce an even greater separation. Likewise, between items at module scope, if there are multiple single line, related functions there might be no newlines. Mostly functions are separated by one line, sometimes grouped using multiple lines. Furthermore, it is really easy to fix manually - you just delete them, its not like you have to re-lay out code. There seem to be some cases we can safely forbid, e.g., blank lines at the start of end of a block. For other uses I see a few options: 1. continue to do preserve all newlines 2. preserve 0, 1, or 2 blank lines, e.g., a 5 line gap would be reduced to 2. 3. preserve 0 or 1 blank lines, e.g., a 5 line gap would be reduced to 1. 4. enforce 1 line between all items and do preserve function bodies (or reduce multiple lines to 1 inside function bodies). I prefer 1 or 3 - I think 4 is too strict, and 2 is unnecessary.

I would favor approach 3 as well, along with guidelines about top level, start and end of block, and similar.

[chriskrycho]

I'd strongly prefer option 2 (edit: if we transform anything at all; [1] is also fine), because I do (borrowing from Python) tend to use 2 blank lines at the top level, and especially between different sections. I find extra spaces very helpful for visually separating logically/semantically distinct sections of the code, especially the use statements, distinct data structures and their implementations, and standalone functions. I would be really frustrated to have rustfmt collapse those.

Example

//! Some module docs
//!
//! More module docs. All the docs. Docs and docs and docs.


// First-party dependencies
use std::String;
use std::borrow::Borrow;

// Third-party dependencies
use foo::Foo;


/// Hey look, a `Quux`.
pub struct Quux {
    // ...
}

impl Quux {
    /// Give me a `Quux`!
    pub fn new() -> Quux {
        // ...
   }
}

impl Borrow<T> for Quux {
  fn borrow(&self) -> &T {
    // ...
  }
}


/// This is a `Bar`.
pub enum Bar {
    VariantA,
    VariantB(i32),
    VariantC { q: u64 },
}

impl Bar {
    // ...
}


/// Hey, sometimes we have standalone functions, too
pub fn baz(bar: Bar) -> Quux {
    // ...
}

[nrc]

I used to use 2 line spaces as significant, however, my feeling more recently that this is too subtle to be useful and that if I want to separate groups of items, then they should be in different files, or I should use a comment to separate. Having said that, I am still somewhat sympathetic to this approach.

We could have option 3, with option 2 as a config option. I think this is quite suitable as a config option - it seems reasonable to disagree with the default, and it doesn't make the code unfamiliar to change the value.

[tshepang]

Though I come from Python, I've come to appreciate that there is no fussing about "is it one space, or is it two" in Rust. I see no readability issue, and I've even come to visually appreciate the compactness the one-space approach that promotes.

Looking at @chriskrycho preference, I be sad... way too sparce, especially with those doc comments.

[nrc]

Entering FCP:

• by default Rustfmt will reduce whitespace between items to a single blank line. If items are not separated by blank lines, they will not be inserted.
• items on the same line will be put on separate lines with no blank lines between them
• Rustfmt should be configurable to specify the minimum and maximum number of line breaks allowed.

[solson]

by default Rustfmt will reduce whitespace between items to a single blank line. If items are not separated by blank lines, they will not be inserted.

To be clear, this also applies to statements, right? E.g. if the max is set to 1 blank line, we should change the following:

fn foo() {
    bar();
    baz();


    quux();
}

Into this:

fn foo() {
    bar();
    baz();

    quux();
}

[jplatte]

Rustfmt should be configurable to specify the minimum and maximum number of line breaks allowed.

The minimum number of (consecutive) line breaks allowed? Is this talking about a minimum between certain elements, or a rule like "a blank line must always have another blank line before or after it"? Because the former sounds like it would have to be multiple options for different contexts, and the latter would be very weird IMHO.

[nrc]

To be clear, this also applies to statements

We could do. What do you think? I'm a little twitchier about statements than items, just because people are more likely to put spacing in, but I think it makes sense to apply the same treatment.

[nrc]

The minimum number of (consecutive) line breaks allowed?

Yeah, so you'd get the following formatting with the various settings:

// 0
fn foo() {} fn bar() {}

// 1
fn foo() {}
fn bar() {}

// 2
fn foo() {}

fn bar() {}

The default would be 1.

I don't think different contexts would require different values. We might not want to apply this to statements, only to items, or have different values for items and statements.

[solson]

With regards to settings, to match what I do today, I would force one space between items (1...1) but zero or one space between statements (0...1).

Given these items (EDIT: made them multi-line. My comment below addresses single-line items):

fn foo() {
    // ...
}
fn bar() {
   // ...
}


fn baz() {
   // ...
}

I would produce:

fn foo() {
    // ...
}

fn bar() {
    // ...
}

fn baz() {
    // ...
}

But given these similar statements:

foo(); bar();


baz();

I would produce:

foo();
bar();

baz();

Basically, I find value in user-controlled statement spacing but not in user-controlled item spacing. Items are usually clearly separated by doc comments or impl grouping instead. You can also demarcate explicit sections with plain top-level comments between items. Statement grouping is more fluid.