From af62a1f9c3aa39c5d26646058c125e142383ee6d Mon Sep 17 00:00:00 2001 From: cartermp Date: Sat, 24 Nov 2018 15:26:14 -0800 Subject: [PATCH 1/3] Add whitespace formatting guidelines --- docs/fsharp/style-guide/formatting.md | 50 +++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/fsharp/style-guide/formatting.md b/docs/fsharp/style-guide/formatting.md index 04bcaf5b23aa9..ee087a4e32002 100644 --- a/docs/fsharp/style-guide/formatting.md +++ b/docs/fsharp/style-guide/formatting.md @@ -25,6 +25,56 @@ When indentation is required, you must use spaces, not tabs. At least one space That said, indentation of programs is a subjective matter. Variations are OK, but the first rule you should follow is *consistency of indentation*. Choose a generally accepted style of indentation and use it systematically throughout your codebase. +## Formatting whitespace + +F# is whitespace-sensitive. Although most semantics from whitespace are covered by proper indentation, there are some other things to consider. + +### Formatting operators in arithmetic expressions + +Always use whitespace around binary arithmetic expressions: + +```fsharp +let subtractThenAdd x = x - 1 + 3 +``` + +Unary `-` operators should never have trailing whitespace: + +```fsharp +// OK +let negate x = -x + +// Bad +let negateBad x = - x +``` + +It is important to always surround binary operators with whitespace and never have trailing whitespace with a unary operator. Failing to do so can lead to code that may accidentally negate a value! + +### Surround a custom operator definition with whitespace + +Always use whitespace to surround an operator definition: + +```fsharp +// OK +let ( !> ) x f = f x + +// Bad +let (!>) x f = f x +``` + +For any custom operator that could start with `*`, you'll need to add a whitespace to the beginning of the definition to avoid a compiler ambiguity. Because of this, it is recommended that you simply surround the definitions of all operators with a single whitespace character. + +### Surround function parameter arrows with whitespace + +When defining the signature of a function, use whitespace around the `->` symbol: + +```fsharp +// OK +type MyFun = int -> int -> string + +// Bad +type MyFunBad = int->int->string +``` + ## Formatting blank lines * Separate top-level function and class definitions with two blank lines. From 2136e638125acf458d18a454f5303131241b3d68 Mon Sep 17 00:00:00 2001 From: cartermp Date: Mon, 26 Nov 2018 07:43:28 -0800 Subject: [PATCH 2/3] Feedback and reword a bit --- docs/fsharp/style-guide/formatting.md | 27 +++++++++++++++++---------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/fsharp/style-guide/formatting.md b/docs/fsharp/style-guide/formatting.md index ee087a4e32002..6b29f7f97c806 100644 --- a/docs/fsharp/style-guide/formatting.md +++ b/docs/fsharp/style-guide/formatting.md @@ -25,19 +25,19 @@ When indentation is required, you must use spaces, not tabs. At least one space That said, indentation of programs is a subjective matter. Variations are OK, but the first rule you should follow is *consistency of indentation*. Choose a generally accepted style of indentation and use it systematically throughout your codebase. -## Formatting whitespace +## Formatting white space -F# is whitespace-sensitive. Although most semantics from whitespace are covered by proper indentation, there are some other things to consider. +F# is white space sensitive. Although most semantics from white space are covered by proper indentation, there are some other things to consider. ### Formatting operators in arithmetic expressions -Always use whitespace around binary arithmetic expressions: +Always use white space around binary arithmetic expressions: ```fsharp let subtractThenAdd x = x - 1 + 3 ``` -Unary `-` operators should never have trailing whitespace: +Unary `-` operators should always have the value they are negating immediately follow: ```fsharp // OK @@ -47,11 +47,18 @@ let negate x = -x let negateBad x = - x ``` -It is important to always surround binary operators with whitespace and never have trailing whitespace with a unary operator. Failing to do so can lead to code that may accidentally negate a value! +Adding a white-space character after the `-` operator can lead to confusion for others. -### Surround a custom operator definition with whitespace +In summary, it's important to always: -Always use whitespace to surround an operator definition: +* Surround binary operators with white space +* Never have trailing white space after a unary operator + +The binary arithmetic operator guideline is especially important. Failing to surround a binary `-` operator, when combined with certain formatting choices, could lead to interpreting it as a unary `-`. + +### Surround a custom operator definition with white space + +Always use white space to surround an operator definition: ```fsharp // OK @@ -61,11 +68,11 @@ let ( !> ) x f = f x let (!>) x f = f x ``` -For any custom operator that could start with `*`, you'll need to add a whitespace to the beginning of the definition to avoid a compiler ambiguity. Because of this, it is recommended that you simply surround the definitions of all operators with a single whitespace character. +For any custom operator that starts with `*`, you'll need to add a white space to the beginning of the definition to avoid a compiler ambiguity. Because of this, it's recommended that you simply surround the definitions of all operators with a single white-space character. -### Surround function parameter arrows with whitespace +### Surround function parameter arrows with white space -When defining the signature of a function, use whitespace around the `->` symbol: +When defining the signature of a function, use white space around the `->` symbol: ```fsharp // OK From 0fffc7034eae28370b512ed6a8660fb1fe34a814 Mon Sep 17 00:00:00 2001 From: cartermp Date: Mon, 26 Nov 2018 07:48:48 -0800 Subject: [PATCH 3/3] Update ms.date --- docs/fsharp/style-guide/formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/fsharp/style-guide/formatting.md b/docs/fsharp/style-guide/formatting.md index 6b29f7f97c806..7407af646e9d8 100644 --- a/docs/fsharp/style-guide/formatting.md +++ b/docs/fsharp/style-guide/formatting.md @@ -1,7 +1,7 @@ --- title: F# code formatting guidelines description: Learn guidelines for formatting F# code. -ms.date: 05/14/2018 +ms.date: 11/26/2018 --- # F# code formatting guidelines