Function definitions

[joshtriplett]

Part of #25: how should we format and indent function definitions? This includes arguments and their types, generics and their constraints, and the braces; the body of the function then falls under #11. This also interacts with where clauses (#38), which we may want to fold in.

[nrc]

Generics are also covered elsewhere: #29. I'd prefer to keep that and where clauses separate since they also affect many other items.

For reference the current style used in the compiler and std libs and enforced by Rustfmt is:

fn extract_one(&mut self,
               m: FxHashMap<PathBuf, PathKind>,
               flavor: CrateFlavor,
               slot: &mut Option<(Svh, MetadataBlob)>)
               -> Option<(PathBuf, PathKind)> {
    ...
}

To summarise:

• keywords/names are space-separated
• as much as possible on one line, break arguments before generics
• if args are broken:
  • one arg per line
  • pattern and type on one line, space after : only
  • comma terminated
  • visual indented
  • return type on a newline and visual indented with args
• opening brace (or semi-colon) on the same line as return type
• body is block indented.

I think the main alternative is to block indent the args, where there are a few options.

[joshtriplett]

One notable interaction with where clauses: if a function needs a where clause, do you then put the opening brace on the last line of the where clause, or at the start of the following line?

A few variations on block-indentation that I've seen in real code (again, assuming everything doesn't fit on one line):

/* 1: close paren, return type, and brace on one line */
fn extract_one(
    &mut self,
    m: FxHashMap<PathBuf, PathKind>,
    flavor: CrateFlavor,
    slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)> {
    ...
}

/* 2: close paren and return type on one line, brace on next line */
fn extract_one(
    &mut self,
    m: FxHashMap<PathBuf, PathKind>,
    flavor: CrateFlavor,
    slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)>
{
    ...
}

/* 3: close paren with last argument, return type and open brace on next line */
fn extract_one(
    &mut self,
    m: FxHashMap<PathBuf, PathKind>,
    flavor: CrateFlavor,
    slot: &mut Option<(Svh, MetadataBlob)>)
    -> Option<(PathBuf, PathKind)> {
    ...
}

/* 4: close paren with last argument, return type on next line, open brace on next line. */
fn extract_one(
    &mut self,
    m: FxHashMap<PathBuf, PathKind>,
    flavor: CrateFlavor,
    slot: &mut Option<(Svh, MetadataBlob)>)
    -> Option<(PathBuf, PathKind)>
{
    ...
}

Personally, I prefer the first or second option. The third and fourth break the "comma terminated" property.

Of the first and second, I mildly prefer the first (brace on the same line), for consistency with the one-line case. The second will look slightly more familiar to C/C++ users, and provides consistency with the where case.

[nrc]

One notable interaction with where clauses: if a function needs a where clause, do you then put the opening brace on the last line of the where clause, or at the start of the following line?

I think this affects traits, impls etc. in the same way as functions, so we can just discuss that with the rest of where clauses

Thanks for the block layouts! I think 3 is a non-starter because there is no separation between the args/return type and the body. The others look OK to me, I guess I prefer 1 over the others. Is there consensus that we should linebreak before the first argument?

Another option (either block or visual) is to put more than one arg/type pair on each line. I dislike this option, but just putting it out there.

[solson]

+1 for option 1. I find this style really easy to work with (even right now when I don't have rustfmt helping me).

I definitely prefer linebreaking before the first argument in this style.

[joshtriplett]

I prefer the first style with the linebreak before the first argument as well.

[bruno-medeiros]

Prefer option 2 or 1. Some preference towards 2 because it works better for functions with where clauses:

fn extract_one<FOO, BAR>(
    m: FxHashMap<PathBuf, PathKind>,
    slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)>
where 
    FOO : blah::FooTrait + Send,
    BAR : blah::BarTrait + 'static, 
{
    ...
}

I think it's better for the opening brace '{' to start on the same place regardless of the function having a where clause or not - it's a more uniform rule.

[joshtriplett]

I don't find it problematic to move the brace for a where clause, and it seems worth the compactness in the common case.

[nrc]

I don't find it problematic to move the brace for a where clause, and it seems worth the compactness in the common case.

Agreed, that is what we currently do in Rustfmt and std/compiler and it works pretty well.

[quodlibetor]

Something that hasn't been brought up here (but I've seen allusions to elsewhere) is the amount of block indent, assuming block indent is chosen. The thing that I like most about visual indent is the clear separation of blocks. To my mind, function parameters, where clauses, and the function block itself should not be indented the same.

Given this (from above):

(1)

fn extract_one<FOO, BAR>(
    m: FxHashMap<PathBuf, PathKind>,
    slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)>
where 
    FOO : blah::FooTrait + Send,
    BAR : blah::BarTrait + 'static, 
{
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

I would much prefer indentation that draws distinction to the various clauses. where is nice because it's an odd number of letters, so its parameters are automatically oddly indented. The code above manages to break that, even though where is never going to change length. I'd prefer something more like:

(2)

fn extract_one<FOO, BAR>(
        m: FxHashMap<PathBuf, PathKind>,
        slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)>
where FOO : blah::FooTrait + Send,
      BAR : blah::BarTrait + 'static, 
{
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

Maybe m and slot should be indented with 6 spaces to match the indent of where clauses?

(3)

fn extract_one<FOO, BAR>(
      m: FxHashMap<PathBuf, PathKind>,
      slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)>
where FOO : blah::FooTrait + Send,
      BAR : blah::BarTrait + 'static, 
{
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

I don't love what that does to the return value, I think of that as coming "after" the parameters:

(4)

fn extract_one<FOO, BAR>(
      m: FxHashMap<PathBuf, PathKind>,
      slot: &mut Option<(Svh, MetadataBlob)>,
        ) -> Option<(PathBuf, PathKind)>
where FOO : blah::FooTrait + Send,
      BAR : blah::BarTrait + 'static, 
{
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

That's... hideous.

Without where clauses:

(5)

fn extract_one<FOO, BAR>(
      m: FxHashMap<PathBuf, PathKind>,
      slot: &mut Option<(Svh, MetadataBlob)>,
        ) -> Option<(PathBuf, PathKind)> {
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

or maybe:

(6)

fn extract_one<FOO, BAR>(
      m: FxHashMap<PathBuf, PathKind>,
      slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)> {
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

Not great, but I still think a 4-space indent is worse:

(7)

fn extract_one<FOO, BAR>(
    m: FxHashMap<PathBuf, PathKind>,
    slot: &mut Option<(Svh, MetadataBlob)>,
) -> Option<(PathBuf, PathKind)> {
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

[regexident]

To my mind, function parameters, where clauses, and the function block itself should not be indented the same.

This would drive me nuts. 👎

[quodlibetor]

I understand your opinion (when I was first exposed to this idea I hated it) but it does a pretty good job with the pathological case, which I forgot to include, and which is the thing that I most want to avoid:

(8)

fn extract_one<FOO, BAR>(
    m: FxHashMap<PathBuf, PathKind>,
    slot: &mut Option<(Svh, MetadataBlob)>) {
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

compare to:

(9)

fn extract_one<FOO, BAR>(
        m: FxHashMap<PathBuf, PathKind>,
        slot: &mut Option<(Svh, MetadataBlob)>) {
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

and

(10)

fn extract_one<FOO, BAR>(
      m: FxHashMap<PathBuf, PathKind>,
      slot: &mut Option<(Svh, MetadataBlob)>) {
    let something = woah()
    for thing in my_real_code() {
        do_something_else()
    }
}

Again, I don't really care how block indenting happens, I just don't like it when it's hard to tell when function parameters end and function bodies begin. Similar to the reason that I prefer visual indent for method chains, it seems worth having "lines of thought" that distinguish different kinds of action.

[nrc]

Just to be clear, although I expressed a preference for the one of the block-formatted options. I massively prefer the visually indented option. I think that it looks better because we don't have a (\n. I feel that because of the lack of nesting, most of the arguments in favour of block formatting don't apply here, most editors make visual indentation easy to apply, and it is consistent with much code already in the wild (in particular, the std libs). The only reason I'd prefer block indentation is for consistency with expressions, where it seems very likely we'll prefer block indentation. However, I think the benefits of aesthetics and consistency with existing code outweigh that.

[joshtriplett]

The main downside of visual indentation here: if you change the function name, or if you change the generic parameters, you'll have to re-indent every line.

I expect the common case to remain a one-liner. This only matters for functions with enough parameters to need to wrap to multiple lines. And in those cases, I still prefer block indent for consistency.

[nrc]

The main downside of visual indentation here: if you change the function name, or if you change the generic parameters, you'll have to re-indent every line.

My experience is that this is trivially easy to do manually in any decent editor (again in contrast with expressions, where it seems to often require reformatting). And of course Rustfmt will do it for you even more easily.

I expect the common case to remain a one-liner.

Agreed, although 'common case' here means maybe 66% or 75%, rather than 90% or 99%

[solson]

Visual indentation often pushes the arguments much too far to the right, forcing the arguments themselves to be further broken into multiple lines to fit. In my experience it creates a mess far too often to be worthwhile.