Code Organization Section

[SpiralOSS]

@bartelink When I first started with F#, I had a little trouble with the namespace and module syntax when it was at the top of the file.

I made a section on Code Organization, but wanted to get some feedback before bringing it all the way to a PR.

https://github.com/SpiralOSS/fsharp-cheatsheet/blob/feat/code_organization/docs/fsharp-cheatsheet.md#files

If you have a moment, could you take a look and tell me whether it looks like it would be helpful?

Thanks GregH

[bartelink]

It's definitely worth covering, but its damn tricky to elevate the core concepts while keeping it scannable given how much stuff can overlap in there. In particular rec is probably worth pulling off to the side, and maybe the overall thing is better addressed by having sections about

• ordering and that being central to type inference (should be very early on in the sheet and a given)
• module vs type
• namespace rec / module rec (reminder that ordering is a feature, not a bug)

Not sure that table truly works, even if I can see it straightening out quite a few things in a learners map of the world.

I't tend to have File, Namespace, Type and Module as headings

While there's a commonality between namespaces and module in that you

• need to start a file with one or the other
• can make them rec

... I think that's not the point ...

The high order bits for me are:

• namespaces are dotted strings that prefix names, no more, no less (many will assume/know that from C#, but I'd try to convey that namespace is not a special kind of module nor vice versa, even if it cna look like that)
• keep related stuff in a file (not a file per thing like C#)
• rec is for codegen or very specific cases - it's not a gamechanger for F# and does not change the fact that order dependence is annoying at first but a core value prop of the language once you get over the hump
• modules are the key building block of F# apps (and are static Types from the LR perspective). They can have static state and static init stuff via do.

I'd try to tersely cover

• files can be either: single namespace, multi namespace, or single module (the last file has some special relaxations, but they can figure that out)
• types can also have primary ctors, ctor, state, optional arguments, overloads but are not preferred unless you need such things. They can have static stuff via static let and static member, but default is that things are the state of the type. (Some section somewhere should convey that its pretty normal to implement most things in modules and then compose a type calling those functions as one liners, which means you can test easily, and read the type def easily too)
• ordering is strict for files and refs inside things (but rec can relax it, member is an exception to the rule, and mutually recursive ands can work too). While rec is interesting to describe, its not part of mainline usage of the language so should probably not get equal billing in a cheatsheet (but perhaps an example showing type A and B where A uses B with you want to cover A first vs doing it with namespace rec vs declaring B first)
• modules can nest, nothing else can (i.e. convey that types cant nest, and that namespaces inside a file start anew)
• functions can't go in namespaces (but an autopen module can sometimes be reasonable)
• a file must start with a namespace (can be global or be a module-file)
• you can open modules and namespaces (and you can alias them); you open type Types (probably mention that opens are order sensitive)

And then illustrate - possibly showing equivalence between a file-module and doing the same thing as a file with a namespace and the same module nested within. That section should show examples with very minimal text (ideally just terse comments). i.e. "or just read the intro already" is implied

Maybe show

namespace A.B

[<AutoOpen>]
module private Helpers =
    let calc x = x * 2 // A.B.calc
    let frob x = x + 1 

module C =
    let computeC () = frob 5
    do printfn "D initialized"
    module D = // externally, this is `A.B.C.D`
        let x = calc 5

vs

module A.B.C

let private frob x = x + 1
let computeC () = frob 5 // A.B.C.computeC

let private calc x = x * 2 // A.B.C.calc 
module D = // externally, this is `A.B.C.D`
    do printfn "D initialized"
    let x = calc 5

vs

module rec A.B.C

let computeC () = frob 5
module D = // externally, this is `A.B.C.D`
    do printfn "D initialized"
    let x = calc 5

let private calc x = x * 2 // A.B.C.calc 
let private frob x = x + 1

(Best to do a draft PR in circumstances like this; e.g. for me to hang other small comments such as: no need to the 'for the OO people' qualifiers)

[SpiralOSS]

Thank you for the lengthy response! I can see your point (about it not being the point). Let me digest and distill.

[bartelink]

I haven't read Stylish F#, F# in Action or https://leanpub.com/essential-fsharp, nor have I tutored anyone new to F# for quite some time so don't necessarily have any particularly well thought out ways of presenting these things

I read Expert F# twice, Real world FP by Petricek/Skeet ages ago mainly because there was not that much more when I was learning. Expert F# spoke to me, but it's defintely not succinct.

(Also I trust you've read Domain Modelling made Functional - if not, it's definely a must read)