Record formatting feedback

[kspeakman]

The 2 recommended multi-line record formattings can be problematic. And in fact trying to use the above recommendations as a beginner was a very frustrating experience. Here's why.

The first multi-line form has editor-based issues that may require manual, line-by-line correction on indent/outdent. I stopped using this form because of the tedious formatting corrections. For example, In VS 2017 outdent will cause later fields to shift out of line with the first field, creating a compiler error until corrected.

// before outdent
    let myRecord =
        { Field1 = 1
          Field2 = " " }

// after outdent (Shift-Tab), compile error: No assignment given for field Field2
let myRecord =
    { Field1 = 1
        Field2 = " " }

The second multi-line form simply does not compile with some type definition features or provides warnings with some constructions.

type IMyInterface = interface end

// compiler error: Unexpected keyword interface
type MyRecord = {
    MyField : int
}
interface IMyInterface

// warning: "possible incorrect indentation"
let foo a =
    a
    |> Option.map (fun x -> {
            MyField = x
        })

The only record syntax I've found that always "just works" is this.

// this works with all type features, like interface
type MyRecord =
    {
        SomeField : int
    }
    interface IMyInterface

// no warning
let foo a =
    a
    |> Option.map (fun x ->
        {
            MyField = x
        })

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 8c09996f-24ac-cf39-ef43-d7909cbc2b89
• Version Independent ID: 1efdd523-8552-6421-e149-74f76826ef8f
• Content: F# code formatting guidelines
• Content Source: docs/fsharp/style-guide/formatting.md
• Service: unspecified
• Product: dotnet-fsharp
• GitHub Login: @cartermp
• Microsoft Alias: phcart

[abelbraaksma]

@mathid, @cartermp, you closed #6775 which also addresses this issue. Though one could argue it could be further improved, esp. about the syntaxes that "sometimes" work (only with verbose syntax, but even than, as shown above, it can still fail sometimes with a warning).

I.e., the record syntax says "Placing the opening token on the same line and the closing token on a new line is also fine:", but this is only sometimes fine and can lead to warnings or even errors. I think it should be un-recommended, but a warning about that syntax should remain.

I'd also like to suggest to change the line "// Unusual in F#" on the record syntax that has { and } on their own lines. I use a-plenty, for the same reason the OP here uses it: it eases formatting and in- and outdenting. While more verbose, I think it is better readable.

Finally, the sentence "The same rules apply for list and array elements.", that also applies to the warnings (mentioned above, but not yet in the text). Having the [ on the same line as the assignment and then start on the next line with items, can lead to compile errors and/or warnings. I think we should in fact put a red flag here and say that such syntax is not OK.

// works (but cannot be indented/outdented properly)
let foo = 
    [   1
        2
        3
    ] |> List.map id

// always works
let foo = 
    [ 
        1
        2
        3
    ] |> List.map id

// syntax error
let foo = [   
    1
    2
    3
] |> List.map id

// syntax error
let foo = [  
        1
        2
        3
    ] |> List.map id

In short, I wholeheartedly agree with the OP and think we can do better and provide guidelines that always work. Or fix the compiler so that the guidelines can actually be applied ;).

[cartermp]

Unfortunately, I'm not sure if we'll change this one. Changing bracket-related formatting like that is pretty universally against core F# formatting in the F# codebase and the bulk of code that you'll find online. Bucking that trend is something I see as more negative, unfortunately.

[abelbraaksma]

@cartermp, could you elaborate how it (the guideline) is used currently? Because as the examples show above, it cannot even be compiled. meaning that we have a guideline that, if followed, leads to non-compilable code.

Are you sure the guideline is like what is used in F#'s own codebase, if so, why doesn't it lead to compile errors there?

[cartermp]

@abelbraaksma We do not write code as you have written; however, based on this and some more thought I decided it's worth bucking the trend and going with brackets on their own lines when piping or adding members.

[kspeakman]

I like these changes. Prior to this discussion I had not even realized that the with keyword would allow the expanded syntax below to work with interfaces.

type MyRecord = {
    Prop1: string
} with interface IMarker

I think (probably like most of you) it is not great practice to use interfaces or class properties with F# record and union types. However, it is sometimes needed for interop scenarios (as can be seen in F#'s own List definition). In any case I am glad to see valid syntaxes documented.

I was surprised to see the concise syntax recommended as the default. It looks nice in online examples, but I find it not very pragmatic for everyday use (issues: git diffs, cut-paste, in/out-denting). But no biggie since there are multiple options.

Thanks!

[abelbraaksma]

@cartermp, excellent additions, thanks. I made a few comments (sorry for repeating myself, there was no review button).