Update Tutorial Script #2122

cartermp · 2016-12-28T23:00:31Z

I've made quite a few changes to the Tutorial project to align it a bit more with the Tour of F# document. That means a few things:

Many more links to documentation for modules which demonstrate language features
Some more additions to call out more language features within a particular area
Some more module-level organization
More comments in places to explain things
Minor changes, like adding line breaks to |> pipelines and changing from %A to a more concrete format type when possible

When this is merged (pending changes), I'll be updating the Tour document so that the backing code samples pull from this same source file. I'll probably be modifying a bit of the text, but there shouldn't be too much to change in that document.

I may also push another change which endeavors to add more printfn statements.

cc @dsyme

saul · 2016-12-29T00:41:18Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx



-/// First some basics on integers and numbers
+/// Modules are the primary way to organize functions and values in F#. This module contains some


Should we explain the difference between // comments and triple-slash comments? It looks like a mix has been used in this document which could be confusing as to what the 'defacto' comment style is, and when/where each type should be used.

Called out the different comment types up top.

saul

This looks like a really great addition to ease beginners into F#, especially if they're from an imperative background 👍

saul · 2016-12-29T00:42:34Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

    printfn "The result of squaring the integer 4573 and adding 3 is %d" result1

-    /// When needed, annotate the type of a parameter name using '(argument:type)'
+    /// When needed, annotate the type of a parameter name using '(argument:type)'.  Parenthesis are required.


We should be using the plural of parenthesis (parentheses).

saul · 2016-12-29T00:44:35Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx


-    /// Strings can also use @ to create a verbatim string literal
-    let string3 = @"c:\Program Files\"
+    /// Strings can also use @ to create a verbatim string literal.


Maybe explain that verbatim strings will ignore escape sequences such as \n, \t etc. It may also be useful to demonstrate the logical equivalent: "C:\Program Files\"

saul · 2016-12-29T00:48:29Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+            printfn "%s" (showPlayingCard card)
+
+    // Single-case DUs are often used for domain modeling.  This can buy you extra type safety
+    // over primitive types such as strings and ints.


...as they cannot be implicitly cast to/from the type they wrap. For example, a function that takes a parameter of type Address will not accept a value of type string (and vice versa).

Addressed (heh, that was a pun).

saul · 2016-12-29T00:49:14Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+            elif item < x then Node(x, insert item left, right) // Call into left subtree.
+            else Node(x, left, insert item right) // Call into right subtree.
+
+    /// Discriminated Unions can also be represented as structs via the 'Struct' attribute.


When would you use this? Why would you prefer to use a struct DU over a reference DU?

Addressed this with a basic statement. There should be some documentation somewhere where we could point to about structs v. reference types for performance, but since it's a bit of a tricky area that's subject to that specific code, I've opted not to explain anything here.

smoothdeveloper

Nice showcase of the syntax for main constructs.

smoothdeveloper · 2016-12-29T00:45:36Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+    ///
+    /// The second line below will fail to compile because of this.  Uncomment it to see what happens.
    let sampleStructTuple = struct (1, 2, 3)
+    //let thisWillNotCompile: (int*int) = struct (1, 2)


Consider adding

//let thisWillCompile: struct (int*int) = struct (1, 2)

?

smoothdeveloper · 2016-12-29T00:48:40Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

-/// A record is a collection of data items brought together into one object.
+
+/// Records are an aggregate of named values, with optional members (such as methods).
+/// They are immutable and have structural equality semantics.


/// They are immutable by default and have structural equality semantics.

smoothdeveloper · 2016-12-29T00:50:59Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+    ///
+    /// This represents a Binary Search Tree, with one case being the Empty tree,
+    /// and the other being a Node with a value and two subtrees.
+    type 'T BST =


use BST<'T> notation to match dotnet syntax?

forki · 2016-12-29T09:28:15Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

 //     https://docs.microsoft.com/en-us/dotnet/articles/fsharp/
 //
+// To see this tutorial in documentation form, see:
+//     https://docs.microsoft.com/en-us/dotnet/articles/fsharp/tour


Is this URL stable?

forki · 2016-12-29T09:28:51Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+

-// Open namespaces using 'open'
+// Open namespaces using the 'open' directive.


directive? Maybe use "keyword" ?

forki

This is great. only couple of minor suggestions

forki · 2016-12-29T09:29:25Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+/// Modules are the primary way to organize functions and values in F#. This module contains some
+/// basic values involving basic numeric values computed in a few different ways.
+///
+/// To learn more, see: https://docs.microsoft.com/en-us/dotnet/articles/fsharp/language-reference/modules


same here. we need to make sure it's a stable url

forki · 2016-12-29T09:31:21Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

    /// Conditionals use if/then/elid/elif/else.
    ///
-    /// Note that F# uses whitespace indentation-aware syntax like Python.
+    /// Note that F# uses whitespace indentation-aware syntax, similar to languages like Python or Ruby.


IIRC Ruby is not whitespace sensitive - then have things like end keywords. http://stackoverflow.com/a/17052327/145701

forki · 2016-12-29T09:32:26Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+    let string4 = """The computer said "hello world" when I told it to!"""

-    /// String concatenation is '+'. Also see String.concat, System.String.Join and others.
+    /// String concatenation is normally done with the '+' operator.


the normally should be removed

normally seems fine here. There are after all other ways of concatenating strings..

It pretty much depends on context. If you do it in a big loop you "normally" want to use a string builder. But I'm fine with keeping it.

forki · 2016-12-29T09:33:52Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

-/// Many other collection types are available in System.Collections.Generic,
-/// System.Collections.Immutable and other libraries.
-module ListsAndArrays = 
+/// Lists are ordered, immutable, singly-linked lists.  They are eager in their evaluation.


immutability is a concept that is not used in many languages yet. Can we link to a definition?

This is actually something covered in the documentation: https://docs.microsoft.com/en-us/dotnet/articles/fsharp/tour#functions-and-modules

let bindings are also how you bind a value to a name, similar to a variable in other languages. let bindings are immutable by default, which means that once a value or function is bound to a name, it cannot be changed in-place. This is in contrast to variables in other languages, which are mutable, meaning their values can be changed at any point in time. If you require a mutable binding, you can use let mutable ... syntax.

I'm a bit wary about copying in that text (or something like it) into comments, but I agree that it should probably be mentioned near the beginning here and a link to some documentation ought to be provided.

forki · 2016-12-29T09:34:25Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

    let list1 = [ ]  

-    /// This is a list with 3 elements.
+    /// This is a list with 3 elements.  ';' is used to separate elements.


or line breaks. Please add a sample with line breaks

Good feedback

forki · 2016-12-29T09:35:44Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

                  yield System.DateTime(2012, month, day) ]

+    // Print the first 5 elements of 'daysList' using 'List.take'.
+    printfn "The first 5 days of 2017 are: %A" (daysList |> List.take 5)


did we already introduce the pipe?

I was thinking about this, and it's kind of difficult to introduce piping (and composition with >>) without also having Lists/Arrays/etc, since those are some of the most natural data structures to process data via a pipeline. I think that if we have pipelines prior to this section with some basic lists then it should be okay.

KevinRansom · 2016-12-29T16:52:11Z

@cartermp
I will pull this as is. These improvements are great, can you prepare and submit a PR with:

Stable Urls for the links.
A module discussing mutability and immutability.

Thanks

Kevin

forki · 2016-12-29T16:52:56Z

Awesome job!

cartermp · 2016-12-29T16:53:58Z

FYI the links are stable - both the docs.ms and MSDN links are backed by a redirect system, so if documents get moved around then it'll get handled appropriately. I'll prepare a module for mutability v. immutability and pipelines.

forki · 2016-12-29T16:59:53Z

That would be the first time Microsoft links are considered stable. ;-) But I trust you on this.

dsyme · 2016-12-29T22:45:32Z

vsintegration/ProjectTemplates/TutorialProject/Template/Tutorial.fsx

+    open Microsoft.FSharp.Data.UnitSystems.SI.UnitNames
+
+    /// Define a unitized constant
+    let sampelValue1 = 1600.0<meter>          


There's a typo here sampelValue1

Update Tutorial Script

3b83119

msftclas added the cla-not-required label Dec 28, 2016

saul reviewed Dec 29, 2016

View reviewed changes

smoothdeveloper approved these changes Dec 29, 2016

View reviewed changes

Feedback and add more print statements

cf705ed

forki reviewed Dec 29, 2016

View reviewed changes

forki approved these changes Dec 29, 2016

View reviewed changes

KevinRansom merged commit 68d2f08 into dotnet:master Dec 29, 2016

dsyme reviewed Dec 29, 2016

View reviewed changes

cartermp deleted the update-tutorial branch December 30, 2016 00:51



		/// First some basics on integers and numbers
		/// Modules are the primary way to organize functions and values in F#. This module contains some



		// Open namespaces using 'open'
		// Open namespaces using the 'open' directive.

Update Tutorial Script #2122

Update Tutorial Script #2122

Uh oh!

Conversation

cartermp commented Dec 28, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

saul left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

smoothdeveloper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

forki left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cartermp Dec 29, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KevinRansom commented Dec 29, 2016

Uh oh!

forki commented Dec 29, 2016

Uh oh!

cartermp commented Dec 29, 2016

Uh oh!

forki commented Dec 29, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

cartermp Dec 29, 2016 •

edited

Loading