dotnet new console template considerations for dotnet 5.0

[drk-mtr]

I wasn't sure which repo this should go against, please feel free to remove if it should live somewhere else.

I'm hoping to understand the rationale behind the changes to the F# template when running dotnet new in dotnet 5.0 and understand whether people feel it's worth making some tweaks.

Firstly for context, here's the content from Program.fs when we do a dotnet new console:

// Learn more about F# at http://docs.microsoft.com/dotnet/fsharp

open System

// Define a function to construct a message to print
let from whom =
    sprintf "from %s" whom

[<EntryPoint>]
let main argv =
    let message = from "F#" // Call the function
    printfn "Hello world %s" message
    0 // return an integer exit code

I guess my question is essentially - is this designed to help complete newcomers learn, or does it help the "average user" get up and running quickly from the command line and prove that they have a working environment?

If it's the former, I feel we could do a slightly better job. If it's the latter, I feel it's a bit bloated. I am very biased towards wanting something that does the latter personally, as I don't think the template is the correct vehicle through which to introduce people - but I appreciate that's my bias, so I've tried to give some ideas below on how it could be tweaked if this is intended to be an introduction for new people.

Initial ramblings (disclaimer: I'm trying to play devil's advocate here, I hope this doesn't sound rude!):

/// Is this necessary? It's the third result when I search online - all users will know how to search 
/// "learn fsharp" to find the resource. It's just another thing to delete. Can we remove?
// Learn more about F# at http://docs.microsoft.com/dotnet/fsharp

open System

/// This "from whom" terminology adds confusion. How does a newcomer intuitively know which 
/// bit is the function name and which bit is the argument? Naming the argument "whom" seems
/// odd to me as a native English speaker who knows the basics of F#. If the user is trying
/// to understand this purely based on context, how are they to know that `from` is not a keyword
/// in F#. Also I'd assume it's not the friendliest choice of terms for people who don't speak
/// English as their first language (though that's very speculative!). Would you ever call a 
/// function `from` in this context in the real world? Etc.
// Define a function to construct a message to print
let from whom =
    sprintf "from %s" whom

[<EntryPoint>]
let main argv =
    let message = from "F#" // Call the function
    printfn "Hello world %s" message

    /// A newcomer might not understand the convention that a code comment describes what the
    /// code does. They might think it is something they are being told to do, or a feature
    /// that the program is meant to have. Maybe it prints the integer to the console...?
    /// Why must it be done? What is an integer, or an exit code? Why do we start to explain this 
    /// but not `argv` or `EntryPoint`? A comment at the end of a line is harder to quickly delete
    /// than a comment on its own line.
    0 // return an integer exit code

Suggestion if we want something to help people learn

I don't know whether my explanations here are correct as I'm quite new to it, but they hopefully give an idea of the sort of thing I'd envisage.

// The "open" keyword allows us to import code from other sources.
// In this case, we are importing from "System", which is a core namespace within 
// the dotnet ecosystem that provides a number of commonly used types and functions.
open System

// The "buildHelloWorldMessage" function takes an argument of "message", then uses F#'s 
// built-in "sprintf" function to build our message. The "%s" tells the sprintf function
// that the message it can expect will be of type "string".
let buildHelloWorldMessage message =
    sprintf "Hello World %s" message

// This creates a variable "helloWorldMessage" which contains our message. As we 
// can see, the syntax for creating this is the same as the syntax used to create 
// a function. If we want, we can omit this step altogether by simply passing
// our function and string message (in brackets) when we call the printfn function below.
let helloWorldMessage = buildHelloWorldMessage "from F#"

// All programs must have an "EntryPoint", which is where the code will start executing 
// from. The "argv" parameter is useful if we want to pass arguments to the program
// when running it, but we just ignore it here.
[<EntryPoint>]
let main argv =

    // Here we use F#'s built-in "printfn" function to print our message to the console.
    printfn "%s" helloWorldMessage

    // We return the number 0 at the end of the program to tell the operating system that 
    // execution has completed.
    0 

I imagine the namespaces/modules thing will confuse people if they're coming from something like C#, so if this is for introducing people maybe there should be some reference to that too?

I don't think the comments need to be this verbose to be useful, but just some simple tweaks like avoiding from/whom might be worthwhile if you didn't want to go this far.

Suggestion if we want to keep it purely as a quickstart template

open System

[<EntryPoint>]
let main _ =
    printfn "Hello World"
    0 

[abelbraaksma]

I think this is a very good discussion to have. Perhaps we could split it into two templates? One "guided" template for beginners, and one for more experienced users?

There are a few other things I'd like to add to the discussion:

• Any moderately sized project will have namespaces and modules. I find the un-indented template not very useful, and think it's more useful/idiomatic if it were indented, have a module, and be in a namespace (like in C#, where they default to a namespace name equal to the project name.

  namespace MyProject
  open System
  
  module MyModule = 
      [<EntryPoint>]
      let main _ =
          printfn "Hello World"
          0 

• An extra file for library functions, which most projects will have anyway, may be useful, esp. in the "guided" version.

• An fsi file to show how the public functions are exposed (not sure here, this may feel bloated, most projects use access modifiers).

[drk-mtr]

Strongly agree re. the namespaces / modules. I feel .fsi may be going a bit too deep for a newcomer - but again that may be personal bias creeping in, since I don't really use them and I don't feel that's prevented me from getting a good introduction to F#.

[cartermp]

At this point the template will remain for .NET 5, but some changes could be made to accommodate a best practice. The comment-heavy approach is not something I would want to do.

These template changes were made in response to a series of user studies for newcomers who were found to attempt to define a function when trying to accomplish a task, but ended up defining the function after the main function in the console app. No matter their background (Java, Go, Scala) they tried it this way and ended up horribly confused. So I think it's critically important to show how to do this well, and there is a balance to strike between doing things "right" and just showing something that works so that folks can be successful and iterate. I think placing a function in a module is a good way to augment things.

I'm very hesitant to include more comments than already exist, as user studies have shown that people tend to ignore comments and even documentation that explains this stuff and just try to write code, and if they're looking stuff up, hunt for the first code sample and tinker with it until it works. The more they have to read and the more concepts that are introduced, the worse it gets.

The other alternative - no comments, just a printfn call - is viable since it optimizes for existing programmers and not new ones. Not sure how I feel about that, but aside from a minor tweak to include a module that's the only approach I'd likely accept.

[drk-mtr]

I'll agree with that of course, since my preference is no comments at all!

In which case I would propose we trim the scope of this discussion back to just one thing: re-consider the naming of the "from" function and look at going for something like this:

https://dotnet.microsoft.com/learn/languages/fsharp-hello-world-tutorial/modify

[auduchinok]

I'd vote for replacing from/whom too. Maybe moving to direction of having more explicit names would make things easier?

let printHello name =
    printfn "Hello World from %s" name

[<EntryPoint>]
let main argv =
    printHello "F#"
    0

Also, I agree with having a minimal console app template and a "getting started" template with all the comments and extra function people currently have to remove. I really like how Rust makes it easy to create a project (which is basically almost what we've had for F# before):

fn main() {
    println!("Hello, world!");
}

[cartermp]

Yeah, the from/whom thing should just use different words.

For folks who are interested, the motivation behind the change is here: #6785

Essentially, people new to F#, regardless of having .NET background, all tried to define a function after main and they could get stuck because the error message wasn't clear. Nearly all had the intuition to write a separate function to process some data, but none of them thought to define the function before it was used. I think that more than anything else, this speaks to the idea that "define before use" is a concept that lost in the programming world, as most languages allow defining something after its use in source, and most programmers are accustomed to that.

One approach could have been to improve the error message (without messing with other cases where it emits), but the simpler approach is to just telegraph the fact that functions are defined before they are used in the template itself.

I'd like to try some user studies when .NET 5 is out again to see what people struggle with again. The hypothesis would be that this common problem would not happen anymore, and since the previous template didn't define a function, having it there helped them out.

[KevinRansom]

Grammatically from whom is correct. As a software engineering primer this is terrible. If I had a vote (Oh wait I do :-)), I would go with your suggestion it makes one to one with the just the facts approach of the C# console app template.

In VS we have the tutorial template for learning about F# language constructs. And that is likely where newcomers will need more hand holding.

namespace cs
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
}

The templates are open source and can be found on github here: https://github.com/dotnet/templates/tree/master/src/Templates/DotnetCore

Please CC @cartermp and @KevinRansom on a PR to address this change. When and if that change makes it's way through the system, I will update our desktop equivalents in this repo to match.

[cartermp]

Just to clarify @KevinRansom - the current templates are from user studies where people failed to figure out that functions must be declared before they are used. A follow-up is to do this kind of study again and see if it made a difference. Everything else is just opinions that people have.

[KevinRansom]

@cartermp , that makes perfect sense too.