Рекомендации по форматированию кода F#
В этой статье приведены рекомендации по форматированию кода таким образом, чтобы код F# был следующим:
- Более читаемый
- В соответствии с соглашениями, применяемыми средствами форматирования в Visual Studio Code и другими редакторами
- Аналогично другому коду в Сети
См. также соглашения о кодировании и рекомендации по проектированию компонентов, которые также охватывают соглашения об именовании.
Автоматическое форматирование кода
Средство форматирования кода Fantomas — это стандартное средство сообщества F# для автоматического форматирования кода. Параметры по умолчанию соответствуют этому руководству по стилю.
Настоятельно рекомендуется использовать этот модуль форматирования кода. В командах F# спецификации форматирования кода должны быть согласованы и кодированы с точки зрения файла согласованных параметров для проверка форматирования кода, проверка в репозиторий команд.
Общие правила форматирования
F# использует значительное пробелы по умолчанию и учитывает пробелы. Следующие рекомендации предназначены для предоставления рекомендаций по созданию некоторых проблем, которые могут возникнуть.
Использование пробелов без вкладок
Если отступ требуется, необходимо использовать пробелы, а не вкладки. Код F# не использует вкладки, и компилятор даст ошибку, если символ вкладки обнаружен за пределами строкового литерала или комментария.
Использование согласованного отступа
При отступе требуется по крайней мере одно пространство. Ваша организация может создавать стандарты программирования, чтобы указать количество пробелов, используемых для отступа; два, три или четыре пробела отступа на каждом уровне, где происходит отступ, является типичным.
Рекомендуется четверо пробелов на отступ.
Тем не более чем отступ программ является субъективным вопросом. Варианты являются ОК, но первое правило, которое следует следовать, — согласованность отступа. Выберите общий стиль отступа и используйте его систематически в пределах базы кода.
Избегайте форматирования, чувствительного к длине имени
Старайтесь избегать отступа и выравнивания, которые чувствительны к именованию:
// ✔️ OK
let myLongValueName =
someExpression
|> anotherExpression
// ❌ Not OK
let myLongValueName = someExpression
|> anotherExpression
// ✔️ OK
let myOtherVeryLongValueName =
match
someVeryLongExpressionWithManyParameters
parameter1
parameter2
parameter3
with
| Some _ -> ()
| ...
// ❌ Not OK
let myOtherVeryLongValueName =
match someVeryLongExpressionWithManyParameters parameter1
parameter2
parameter3 with
| Some _ -> ()
| ...
// ❌ Still Not OK
let myOtherVeryLongValueName =
match someVeryLongExpressionWithManyParameters
parameter1
parameter2
parameter3 with
| Some _ -> ()
| ...
Основными причинами для предотвращения этого являются следующие:
- Важный код перемещается вправо
- Для фактического кода осталось меньше ширины
- Переименование может нарушить выравнивание
Избегайте лишних пробелов
Избегайте дополнительного пробела в коде F#, за исключением случаев, описанных в этом руководстве по стилю.
// ✔️ OK
spam (ham 1)
// ❌ Not OK
spam ( ham 1 )
Форматирование комментариев
Предпочесть несколько примечаний с двойной косой чертой для комментариев блока.
// Prefer this style of comments when you want
// to express written ideas on multiple lines.
(*
Block comments can be used, but use sparingly.
They are useful when eliding code sections.
*)
Комментарии должны прописывать первую букву и быть хорошо сформированными фразами или предложениями.
// ✔️ A good comment.
let f x = x + 1 // Increment by one.
// ❌ two poor comments
let f x = x + 1 // plus one
Сведения о форматировании комментариев XML-документа см. в разделе "Форматирование объявлений" ниже.
Выражения форматирования
В этом разделе рассматриваются выражения форматирования различных типов.
Форматирование строковых выражений
Строковые литералы и интерполированные строки можно просто оставить в одной строке, независимо от длительности строки.
let serviceStorageConnection =
$"DefaultEndpointsProtocol=https;AccountName=%s{serviceStorageAccount.Name};AccountKey=%s{serviceStorageAccountKey.Value}"
Интерполированные выражения с несколькими строками не рекомендуется. Вместо этого привязать результат выражения к значению и использовать его в интерполированной строке.
Форматирование выражений кортежей
Экземпляр кортежа должен быть скобочным, а запятые в нем должны следовать один пробел, например : (1, 2). (x, y, z)
// ✔️ OK
let pair = (1, 2)
let triples = [ (1, 2, 3); (11, 12, 13) ]
Обычно принято опустить скобки в сопоставлении шаблонов кортежей:
// ✔️ OK
let (x, y) = z
let x, y = z
// ✔️ OK
match x, y with
| 1, _ -> 0
| x, 1 -> 0
| x, y -> 1
Кроме того, обычно принято пропускать скобки, если кортеж является возвращаемым значением функции:
// ✔️ OK
let update model msg =
match msg with
| 1 -> model + 1, []
| _ -> model, [ msg ]
В итоге предпочитайте круглые скобки экземпляров кортежей, но при использовании кортежей для сопоставления шаблонов или возвращаемого значения считается хорошо, чтобы избежать скобок.
Форматирование выражений приложения
При форматировании приложения функции или метода аргументы предоставляются в той же строке, когда разрешена ширина строки:
// ✔️ OK
someFunction1 x.IngredientName x.Quantity
Не указывайте круглые скобки, если аргументы не требуют их:
// ✔️ OK
someFunction1 x.IngredientName
// ❌ Not preferred - parentheses should be omitted unless required
someFunction1 (x.IngredientName)
// ✔️ OK - parentheses are required
someFunction1 (convertVolumeToLiter x)
Не пропускайте пробелы при вызове с несколькими куриными аргументами:
// ✔️ OK
someFunction1 (convertVolumeToLiter x) (convertVolumeUSPint x)
someFunction2 (convertVolumeToLiter y) y
someFunction3 z (convertVolumeUSPint z)
// ❌ Not preferred - spaces should not be omitted between arguments
someFunction1(convertVolumeToLiter x)(convertVolumeUSPint x)
someFunction2(convertVolumeToLiter y) y
someFunction3 z(convertVolumeUSPint z)
В соглашениях о форматировании по умолчанию пространство добавляется при применении функций нижнего регистра к кортежным или круглым аргументам (даже при использовании одного аргумента):
// ✔️ OK
someFunction2 ()
// ✔️ OK
someFunction3 (x.Quantity1 + x.Quantity2)
// ❌ Not OK, formatting tools will add the extra space by default
someFunction2()
// ❌ Not OK, formatting tools will add the extra space by default
someFunction3(x.IngredientName, x.Quantity)
В соглашениях о форматировании по умолчанию пробел не добавляется при применении прописных методов к кортежным аргументам. Это связано с тем, что они часто используются при свободном программировании:
// ✔️ OK - Methods accepting parenthesize arguments are applied without a space
SomeClass.Invoke()
// ✔️ OK - Methods accepting tuples are applied without a space
String.Format(x.IngredientName, x.Quantity)
// ❌ Not OK, formatting tools will remove the extra space by default
SomeClass.Invoke ()
// ❌ Not OK, formatting tools will remove the extra space by default
String.Format (x.IngredientName, x.Quantity)
Возможно, потребуется передать аргументы функции в новой строке в качестве значения удобочитаемости или потому, что список аргументов или имена аргументов слишком длинны. В этом случае отступ одного уровня:
// ✔️ OK
someFunction2
x.IngredientName x.Quantity
// ✔️ OK
someFunction3
x.IngredientName1 x.Quantity2
x.IngredientName2 x.Quantity2
// ✔️ OK
someFunction4
x.IngredientName1
x.Quantity2
x.IngredientName2
x.Quantity2
// ✔️ OK
someFunction5
(convertVolumeToLiter x)
(convertVolumeUSPint x)
(convertVolumeImperialPint x)
Когда функция принимает один многострочный кортежный аргумент, поместите каждый аргумент в новую строку:
// ✔️ OK
someTupledFunction (
478815516,
"A very long string making all of this multi-line",
1515,
false
)
// OK, but formatting tools will reformat to the above
someTupledFunction
(478815516,
"A very long string making all of this multi-line",
1515,
false)
Если выражения аргументов коротки, разделите аргументы пробелами и сохраните его в одной строке.
// ✔️ OK
let person = new Person(a1, a2)
// ✔️ OK
let myRegexMatch = Regex.Match(input, regex)
// ✔️ OK
let untypedRes = checker.ParseFile(file, source, opts)
Если выражения аргументов длинны, используйте новые линии и отступ одного уровня, а не отступ в левой скобке.
// ✔️ OK
let person =
new Person(
argument1,
argument2
)
// ✔️ OK
let myRegexMatch =
Regex.Match(
"my longer input string with some interesting content in it",
"myRegexPattern"
)
// ✔️ OK
let untypedRes =
checker.ParseFile(
fileName,
sourceText,
parsingOptionsWithDefines
)
// ❌ Not OK, formatting tools will reformat to the above
let person =
new Person(argument1,
argument2)
// ❌ Not OK, formatting tools will reformat to the above
let untypedRes =
checker.ParseFile(fileName,
sourceText,
parsingOptionsWithDefines)
Те же правила применяются, даже если существует только один многострочный аргумент, включая многострочные строки:
// ✔️ OK
let poemBuilder = StringBuilder()
poemBuilder.AppendLine(
"""
The last train is nearly due
The Underground is closing soon
And in the dark, deserted station
Restless in anticipation
A man waits in the shadows
"""
)
Option.traverse(
create
>> Result.setError [ invalidHeader "Content-Checksum" ]
)
Форматирование выражений конвейера
При использовании нескольких строк операторы конвейера |> должны находиться под выражениями, с которыми они работают.
// ✔️ OK
let methods2 =
System.AppDomain.CurrentDomain.GetAssemblies()
|> List.ofArray
|> List.map (fun assm -> assm.GetTypes())
|> Array.concat
|> List.ofArray
|> List.map (fun t -> t.GetMethods())
|> Array.concat
// ❌ Not OK, add a line break after "=" and put multi-line pipelines on multiple lines.
let methods2 = System.AppDomain.CurrentDomain.GetAssemblies()
|> List.ofArray
|> List.map (fun assm -> assm.GetTypes())
|> Array.concat
|> List.ofArray
|> List.map (fun t -> t.GetMethods())
|> Array.concat
// ❌ Not OK either
let methods2 = System.AppDomain.CurrentDomain.GetAssemblies()
|> List.ofArray
|> List.map (fun assm -> assm.GetTypes())
|> Array.concat
|> List.ofArray
|> List.map (fun t -> t.GetMethods())
|> Array.concat
Форматирование лямбда-выражений
Если лямбда-выражение используется в качестве аргумента в многостроковом выражении и за ним следует другие аргументы, поместите тело лямбда-выражения на новую строку, отступ на одном уровне:
// ✔️ OK
let printListWithOffset a list1 =
List.iter
(fun elem ->
printfn $"A very long line to format the value: %d{a + elem}")
list1
Если лямбда-аргумент является последним аргументом в приложении-функции, поместите все аргументы до стрелки в одной строке.
// ✔️ OK
Target.create "Build" (fun ctx ->
// code
// here
())
// ✔️ OK
let printListWithOffsetPiped a list1 =
list1
|> List.map (fun x -> x + 1)
|> List.iter (fun elem ->
printfn $"A very long line to format the value: %d{a + elem}")
Относиться к лямбда-лямбда аналогичным образом.
// ✔️ OK
functionName arg1 arg2 arg3 (function
| Choice1of2 x -> 1
| Choice2of2 y -> 2)
Если перед лямбда-отступом всех аргументов с одним уровнем есть много ведущих или многострочный аргументов.
// ✔️ OK
functionName
arg1
arg2
arg3
(fun arg4 ->
bodyExpr)
// ✔️ OK
functionName
arg1
arg2
arg3
(function
| Choice1of2 x -> 1
| Choice2of2 y -> 2)
Если тело лямбда-выражения имеет длину нескольких строк, следует рассмотреть возможность рефакторинга в локально область область функцию.
Если конвейеры включают лямбда-выражения, каждое лямбда-выражение обычно является последним аргументом на каждом этапе конвейера:
// ✔️ OK, with 4 spaces indentation
let printListWithOffsetPiped list1 =
list1
|> List.map (fun elem -> elem + 1)
|> List.iter (fun elem ->
// one indent starting from the pipe
printfn $"A very long line to format the value: %d{elem}")
// ✔️ OK, with 2 spaces indentation
let printListWithOffsetPiped list1 =
list1
|> List.map (fun elem -> elem + 1)
|> List.iter (fun elem ->
// one indent starting from the pipe
printfn $"A very long line to format the value: %d{elem}")
Если аргументы лямбда-лямбда не помещаются в одну строку или являются многострочных, поместите их на следующую строку, отступив на один уровень.
// ✔️ OK
fun
(aVeryLongParameterName: AnEquallyLongTypeName)
(anotherVeryLongParameterName: AnotherLongTypeName)
(yetAnotherLongParameterName: LongTypeNameAsWell)
(youGetTheIdeaByNow: WithLongTypeNameIncluded) ->
// code starts here
()
// ❌ Not OK, code formatters will reformat to the above to respect the maximum line length.
fun (aVeryLongParameterName: AnEquallyLongTypeName) (anotherVeryLongParameterName: AnotherLongTypeName) (yetAnotherLongParameterName: LongTypeNameAsWell) (youGetTheIdeaByNow: WithLongTypeNameIncluded) ->
()
// ✔️ OK
let useAddEntry () =
fun
(input:
{| name: string
amount: Amount
isIncome: bool
created: string |}) ->
// foo
bar ()
// ❌ Not OK, code formatters will reformat to the above to avoid reliance on whitespace alignment that is contingent to length of an identifier.
let useAddEntry () =
fun (input: {| name: string
amount: Amount
isIncome: bool
created: string |}) ->
// foo
bar ()
Форматирование арифметических и двоичных выражений
Всегда используйте пробелы вокруг двоичных арифметических выражений:
// ✔️ OK
let subtractThenAdd x = x - 1 + 3
Не удалось окружить двоичный - оператор при сочетании с определенным выбором форматирования, может привести к интерпретации его как унарного -.
Унарные - операторы всегда должны быть немедленно следуют значению, которое они отменяют:
// ✔️ OK
let negate x = -x
// ❌ Not OK
let negateBad x = - x
Добавление пробела после того, как - оператор может привести к путанице для других пользователей.
Разделение двоичных операторов по пробелам. Выражения Infix являются ОК для формирования строки в одном столбце:
// ✔️ OK
let function1 () =
acc +
(someFunction
x.IngredientName x.Quantity)
// ✔️ OK
let function1 arg1 arg2 arg3 arg4 =
arg1 + arg2 +
arg3 + arg4
Это правило также применяется к единицам мер в типах и константных заметках:
// ✔️ OK
type Test =
{ WorkHoursPerWeek: uint<hr / (staff weeks)> }
static member create = { WorkHoursPerWeek = 40u<hr / (staff weeks)> }
// ❌ Not OK
type Test =
{ WorkHoursPerWeek: uint<hr/(staff weeks)> }
static member create = { WorkHoursPerWeek = 40u<hr/(staff weeks)> }
Следующие операторы определены в стандартной библиотеке F# и должны использоваться вместо определения эквивалентов. Использование этих операторов рекомендуется, так как он, как правило, делает код более читаемым и идиоматичным. В следующем списке приведены рекомендуемые операторы F#.
// ✔️ OK
x |> f // Forward pipeline
f >> g // Forward composition
x |> ignore // Discard away a value
x + y // Overloaded addition (including string concatenation)
x - y // Overloaded subtraction
x * y // Overloaded multiplication
x / y // Overloaded division
x % y // Overloaded modulus
x && y // Lazy/short-cut "and"
x || y // Lazy/short-cut "or"
x <<< y // Bitwise left shift
x >>> y // Bitwise right shift
x ||| y // Bitwise or, also for working with “flags” enumeration
x &&& y // Bitwise and, also for working with “flags” enumeration
x ^^^ y // Bitwise xor, also for working with “flags” enumeration
Форматирование выражений операторов диапазона
Только добавляйте пробелы вокруг всех выражений .. , не являющихся атомарными.
Целые числа и идентификаторы одного слова считаются атомарными.
// ✔️ OK
let a = [ 2..7 ] // integers
let b = [ one..two ] // identifiers
let c = [ ..9 ] // also when there is only one expression
let d = [ 0.7 .. 9.2 ] // doubles
let e = [ 2L .. number / 2L ] // complex expression
let f = [| A.B .. C.D |] // identifiers with dots
let g = [ .. (39 - 3) ] // complex expression
let h = [| 1 .. MyModule.SomeConst |] // not all expressions are atomic
for x in 1..2 do
printfn " x = %d" x
let s = seq { 0..10..100 }
// ❌ Not OK
let a = [ 2 .. 7 ]
let b = [ one .. two ]
Эти правила также применяются к срезу:
// ✔️ OK
arr[0..10]
list[..^1]
Форматирование выражений
Отступы условных условий зависят от размера и сложности выражений, составляющих их. Напишите их в одной строке, когда:
cond,e1иe2короткие.e1иe2неif/then/elseявляются выражениями сами.
// ✔️ OK
if cond then e1 else e2
Если другое выражение отсутствует, рекомендуется никогда не записывать все выражение в одной строке. Это позволяет различать императивный код от функционального.
// ✔️ OK
if a then
()
// ❌ Not OK, code formatters will reformat to the above by default
if a then ()
Если любое из выражений является многострочный, каждая условная ветвь должна быть многострочный.
// ✔️ OK
if cond then
let e1 = something()
e1
else
e2
// ❌ Not OK
if cond then
let e1 = something()
e1
else e2
Несколько условных условий с elif и отступами выполняются в одном область, что if и else при выполнении правил одного выражения строкиif/then/else.
// ✔️ OK
if cond1 then e1
elif cond2 then e2
elif cond3 then e3
else e4
Если любое из условий или выражений является многострочный, все if/then/else выражение является многострочный:
// ✔️ OK
if cond1 then
let e1 = something()
e1
elif cond2 then
e2
elif cond3 then
e3
else
e4
// ❌ Not OK
if cond1 then
let e1 = something()
e1
elif cond2 then e2
elif cond3 then e3
else e4
Если условие имеет многострочный или превышает допустимость по умолчанию для одной строки, выражение условия должно использовать одну отступ и новую строку.
При if инкапсулирование выражения длинного условия должно выравнивать и then ключевое слово.
// ✔️ OK, but better to refactor, see below
if
complexExpression a b && env.IsDevelopment()
|| someFunctionToCall
aVeryLongParameterNameOne
aVeryLongParameterNameTwo
aVeryLongParameterNameThree
then
e1
else
e2
// ✔️The same applies to nested `elif` or `else if` expressions
if a then
b
elif
someLongFunctionCall
argumentOne
argumentTwo
argumentThree
argumentFour
then
c
else if
someOtherLongFunctionCall
argumentOne
argumentTwo
argumentThree
argumentFour
then
d
Однако лучше использовать стиль рефакторинг длительных условий для привязки или отдельной функции:
// ✔️ OK
let performAction =
complexExpression a b && env.IsDevelopment()
|| someFunctionToCall
aVeryLongParameterNameOne
aVeryLongParameterNameTwo
aVeryLongParameterNameThree
if performAction then
e1
else
e2
Форматирование выражений регистра объединения
Применение различаемых вариантов объединения соответствует тем же правилам, что и приложения функций и методов. Это связано с тем, что имя заглавно, форматировщики кода удалят пробел перед кортежем:
// ✔️ OK
let opt = Some("A", 1)
// OK, but code formatters will remove the space
let opt = Some ("A", 1)
Как и приложения-функции, конструкции, разделенные по нескольким строкам, должны использовать отступ:
// ✔️ OK
let tree1 =
BinaryNode(
BinaryNode (BinaryValue 1, BinaryValue 2),
BinaryNode (BinaryValue 3, BinaryValue 4)
)
Форматирование выражений списка и массива
Запись x :: l с пробелами вокруг :: оператора (:: это оператор infix, следовательно, окруженный пробелами).
Список и массивы, объявленные в одной строке, должны иметь пробел после открывающей скобки и перед закрывающей скобкой:
// ✔️ OK
let xs = [ 1; 2; 3 ]
// ✔️ OK
let ys = [| 1; 2; 3; |]
Всегда используйте по крайней мере одно пространство между двумя отдельными операторами фигурных скобок. Например, оставьте пробел между a [ и a {.
// ✔️ OK
[ { Ingredient = "Green beans"; Quantity = 250 }
{ Ingredient = "Pine nuts"; Quantity = 250 }
{ Ingredient = "Feta cheese"; Quantity = 250 }
{ Ingredient = "Olive oil"; Quantity = 10 }
{ Ingredient = "Lemon"; Quantity = 1 } ]
// ❌ Not OK
[{ Ingredient = "Green beans"; Quantity = 250 }
{ Ingredient = "Pine nuts"; Quantity = 250 }
{ Ingredient = "Feta cheese"; Quantity = 250 }
{ Ingredient = "Olive oil"; Quantity = 10 }
{ Ingredient = "Lemon"; Quantity = 1 }]
Та же направляющая применяется к спискам или массивам кортежей.
Списки и массивы, разделенные по нескольким строкам, следуют аналогичному правилу, как записи:
// ✔️ OK
let pascalsTriangle =
[| [| 1 |]
[| 1; 1 |]
[| 1; 2; 1 |]
[| 1; 3; 3; 1 |]
[| 1; 4; 6; 4; 1 |]
[| 1; 5; 10; 10; 5; 1 |]
[| 1; 6; 15; 20; 15; 6; 1 |]
[| 1; 7; 21; 35; 35; 21; 7; 1 |]
[| 1; 8; 28; 56; 70; 56; 28; 8; 1 |] |]
Как и в случае с записями, объявление открывающих и закрывающих квадратных скобок в собственной строке сделает перемещение кода вокруг и перенос в функции проще:
// ✔️ OK
let pascalsTriangle =
[|
[| 1 |]
[| 1; 1 |]
[| 1; 2; 1 |]
[| 1; 3; 3; 1 |]
[| 1; 4; 6; 4; 1 |]
[| 1; 5; 10; 10; 5; 1 |]
[| 1; 6; 15; 20; 15; 6; 1 |]
[| 1; 7; 21; 35; 35; 21; 7; 1 |]
[| 1; 8; 28; 56; 70; 56; 28; 8; 1 |]
|]
Если выражение списка или массива является правой стороной привязки, вы можете использовать Stroustrup стиль:
// ✔️ OK
let pascalsTriangle = [|
[| 1 |]
[| 1; 1 |]
[| 1; 2; 1 |]
[| 1; 3; 3; 1 |]
[| 1; 4; 6; 4; 1 |]
[| 1; 5; 10; 10; 5; 1 |]
[| 1; 6; 15; 20; 15; 6; 1 |]
[| 1; 7; 21; 35; 35; 21; 7; 1 |]
[| 1; 8; 28; 56; 70; 56; 28; 8; 1 |]
|]
Однако если выражение списка или массива не является правой стороной привязки, например, когда оно находится внутри другого списка или массива, если это внутреннее выражение должно охватывать несколько строк, квадратные скобки должны переходить по собственным строкам:
// ✔️ OK - The outer list follows `Stroustrup` style, while the inner lists place their brackets on separate lines
let fn a b = [
[
someReallyLongValueThatWouldForceThisListToSpanMultipleLines
a
]
[
b
someReallyLongValueThatWouldForceThisListToSpanMultipleLines
]
]
// ❌ Not okay
let fn a b = [ [
someReallyLongValueThatWouldForceThisListToSpanMultipleLines
a
]; [
b
someReallyLongValueThatWouldForceThisListToSpanMultipleLines
] ]
То же правило применяется к типам записей внутри массивов или списков:
// ✔️ OK - The outer list follows `Stroustrup` style, while the inner lists place their brackets on separate lines
let fn a b = [
{
Foo = someReallyLongValueThatWouldForceThisListToSpanMultipleLines
Bar = a
}
{
Foo = b
Bar = someReallyLongValueThatWouldForceThisListToSpanMultipleLines
}
]
// ❌ Not okay
let fn a b = [ {
Foo = someReallyLongValueThatWouldForceThisListToSpanMultipleLines
Bar = a
}; {
Foo = b
Bar = someReallyLongValueThatWouldForceThisListToSpanMultipleLines
} ]
При создании массивов и списков программным способом предпочитайте, ->do ... yield если значение всегда создается:
// ✔️ OK
let squares = [ for x in 1..10 -> x * x ]
// ❌ Not preferred, use "->" when a value is always generated
let squares' = [ for x in 1..10 do yield x * x ]
Более ранние версии F# требуют указания yield в ситуациях, когда данные могут быть созданы условно или могут быть последовательные выражения для оценки. Предпочитайте пропускать эти yield ключевое слово, если только вы не должны компилироваться с более старой версией языка F#:
// ✔️ OK
let daysOfWeek includeWeekend =
[
"Monday"
"Tuesday"
"Wednesday"
"Thursday"
"Friday"
if includeWeekend then
"Saturday"
"Sunday"
]
// ❌ Not preferred - omit yield instead
let daysOfWeek' includeWeekend =
[
yield "Monday"
yield "Tuesday"
yield "Wednesday"
yield "Thursday"
yield "Friday"
if includeWeekend then
yield "Saturday"
yield "Sunday"
]
В некоторых случаях do...yield может помочь в удобочитаемости. Эти случаи, хотя и субъективные, следует учитывать.
Форматирование выражений записей
Короткие записи можно записать в одной строке:
// ✔️ OK
let point = { X = 1.0; Y = 0.0 }
Записи, которые больше не должны использовать новые строки для меток:
// ✔️ OK
let rainbow =
{ Boss = "Jeffrey"
Lackeys = ["Zippy"; "George"; "Bungle"] }
Стили форматирования многостроковых скобок
Для записей, охватывающих несколько строк, существует три часто используемых стиля форматирования: Cramped, Alignedи Stroustrup. Стиль Cramped был стилем по умолчанию для кода F#, так как он, как правило, предпочитает стили, позволяющие компилятору легко анализировать код. Stroustrup Оба Aligned стиля позволяют упростить переупорядочение элементов, что может быть проще рефакторинг кода, с недостатком, что для некоторых ситуаций может потребоваться немного более подробный код.
Cramped: исторический стандарт и формат записи F# по умолчанию. Открывающие скобки идут в той же строке, что и первый член, закрывая скобку в той же строке, что и последний элемент.let rainbow = { Boss1 = "Jeffrey" Boss2 = "Jeffrey" Boss3 = "Jeffrey" Lackeys = [ "Zippy"; "George"; "Bungle" ] }Aligned: квадратные скобки каждый получает собственную линию, выровненную по одному столбцу.let rainbow = { Boss1 = "Jeffrey" Boss2 = "Jeffrey" Boss3 = "Jeffrey" Lackeys = ["Zippy"; "George"; "Bungle"] }Stroustrup: открывая скобка идет на той же строке, что и привязка, закрывающая скобка получает собственную строку.let rainbow = { Boss1 = "Jeffrey" Boss2 = "Jeffrey" Boss3 = "Jeffrey" Lackeys = [ "Zippy"; "George"; "Bungle" ] }
Те же правила стиля форматирования применяются для элементов списка и массива.
Форматирование выражений записи копирования и обновления
Выражение записи копирования и обновления по-прежнему является записью, поэтому аналогичные рекомендации применяются.
Короткие выражения могут помещаться в одну строку:
// ✔️ OK
let point2 = { point with X = 1; Y = 2 }
Более длинные выражения должны использовать новые строки и формат на основе одной из указанных выше соглашений:
// ✔️ OK - Cramped
let newState =
{ state with
Foo =
Some
{ F1 = 0
F2 = "" } }
// ✔️ OK - Aligned
let newState =
{
state with
Foo =
Some
{
F1 = 0
F2 = ""
}
}
// ✔️ OK - Stroustrup
let newState = {
state with
Foo =
Some {
F1 = 0
F2 = ""
}
}
Примечание. Если используется Stroustrup стиль для выражений копирования и обновления, необходимоотступить элементы дальше, чем скопированное имя записи:
// ✔️ OK
let bilbo = {
hobbit with
Name = "Bilbo"
Age = 111
Region = "The Shire"
}
// ❌ Not OK - Results in compiler error: "Possible incorrect indentation: this token is offside of context started at position"
let bilbo = {
hobbit with
Name = "Bilbo"
Age = 111
Region = "The Shire"
}
Сопоставление шаблонов форматирования
| Используйте для каждого предложения совпадения без отступа. Если выражение короткое, можно рассмотреть возможность использования одной строки, если каждая вложенная выражения также проста.
// ✔️ OK
match l with
| { him = x; her = "Posh" } :: tail -> x
| _ :: tail -> findDavid tail
| [] -> failwith "Couldn't find David"
// ❌ Not OK, code formatters will reformat to the above by default
match l with
| { him = x; her = "Posh" } :: tail -> x
| _ :: tail -> findDavid tail
| [] -> failwith "Couldn't find David"
Если выражение справа от стрелки сопоставления шаблонов слишком велико, переместите его на следующую строку, отступив один шаг от него match/|.
// ✔️ OK
match lam with
| Var v -> 1
| Abs(x, body) ->
1 + sizeLambda body
| App(lam1, lam2) ->
sizeLambda lam1 + sizeLambda lam2
Аналогично большому значению, если выражение совпадения имеет многострочный или превышает допустимость по умолчанию однострочного выражения, выражение соответствия должно использовать одно отступ и новую строку.
При match инкапсулирование выражения длинного совпадения должно выравнивать и with ключевое слово.
// ✔️ OK, but better to refactor, see below
match
complexExpression a b && env.IsDevelopment()
|| someFunctionToCall
aVeryLongParameterNameOne
aVeryLongParameterNameTwo
aVeryLongParameterNameThree
with
| X y -> y
| _ -> 0
Однако более подходящий стиль для рефакторинга выражений длинного сопоставления с помощью привязки или отдельной функции:
// ✔️ OK
let performAction =
complexExpression a b && env.IsDevelopment()
|| someFunctionToCall
aVeryLongParameterNameOne
aVeryLongParameterNameTwo
aVeryLongParameterNameThree
match performAction with
| X y -> y
| _ -> 0
Следует избежать выравнивания стрелков совпадения шаблонов.
// ✔️ OK
match lam with
| Var v -> v.Length
| Abstraction _ -> 2
// ❌ Not OK, code formatters will reformat to the above by default
match lam with
| Var v -> v.Length
| Abstraction _ -> 2
Сопоставление шаблонов, введенное с помощью ключевое словоfunction, должно отступить один уровень с начала предыдущей строки:
// ✔️ OK
lambdaList
|> List.map (function
| Abs(x, body) -> 1 + sizeLambda 0 body
| App(lam1, lam2) -> sizeLambda (sizeLambda 0 lam1) lam2
| Var v -> 1)
Использование функций, определенных functionlet или let rec в целом, следует избегать использования в пользу match. Если используется, правила шаблона должны соответствовать ключевое словоfunction:
// ✔️ OK
let rec sizeLambda acc =
function
| Abs(x, body) -> sizeLambda (succ acc) body
| App(lam1, lam2) -> sizeLambda (sizeLambda acc lam1) lam2
| Var v -> succ acc
Форматирование примеров и выражений
Сопоставление шаблонов для типа исключения должно быть отступено на том же уровне, что withи .
// ✔️ OK
try
if System.DateTime.Now.Second % 3 = 0 then
raise (new System.Exception())
else
raise (new System.ApplicationException())
with
| :? System.ApplicationException ->
printfn "A second that was not a multiple of 3"
| _ ->
printfn "A second that was a multiple of 3"
| Добавьте предложение для каждого предложения, за исключением случаев, когда существует только одно предложение:
// ✔️ OK
try
persistState currentState
with ex ->
printfn "Something went wrong: %A" ex
// ✔️ OK
try
persistState currentState
with :? System.ApplicationException as ex ->
printfn "Something went wrong: %A" ex
// ❌ Not OK, see above for preferred formatting
try
persistState currentState
with
| ex ->
printfn "Something went wrong: %A" ex
// ❌ Not OK, see above for preferred formatting
try
persistState currentState
with
| :? System.ApplicationException as ex ->
printfn "Something went wrong: %A" ex
Форматирование именованных аргументов
Именованные аргументы должны иметь пробелы, окружающие =:
// ✔️ OK
let makeStreamReader x = new System.IO.StreamReader(path = x)
// ❌ Not OK, spaces are necessary around '=' for named arguments
let makeStreamReader x = new System.IO.StreamReader(path=x)
При сопоставлении шаблонов с использованием дискриминированных профсоюзов именованные шаблоны форматируются аналогично, например.
type Data =
| TwoParts of part1: string * part2: string
| OnePart of part1: string
// ✔️ OK
let examineData x =
match data with
| OnePartData(part1 = p1) -> p1
| TwoPartData(part1 = p1; part2 = p2) -> p1 + p2
// ❌ Not OK, spaces are necessary around '=' for named pattern access
let examineData x =
match data with
| OnePartData(part1=p1) -> p1
| TwoPartData(part1=p1; part2=p2) -> p1 + p2
Форматирование выражений мутаций
Выражения мутаций location <- expr обычно форматируются в одной строке.
Если требуется многострочный формат, поместите правое выражение в новую строку.
// ✔️ OK
ctx.Response.Headers[HeaderNames.ContentType] <-
Constants.jsonApiMediaType |> StringValues
ctx.Response.Headers[HeaderNames.ContentLength] <-
bytes.Length |> string |> StringValues
// ❌ Not OK, code formatters will reformat to the above by default
ctx.Response.Headers[HeaderNames.ContentType] <- Constants.jsonApiMediaType
|> StringValues
ctx.Response.Headers[HeaderNames.ContentLength] <- bytes.Length
|> string
|> StringValues
Форматирование выражений объектов
Элементы выражения объекта должны быть выровнены с member отступом на одном уровне.
// ✔️ OK
let comparer =
{ new IComparer<string> with
member x.Compare(s1, s2) =
let rev (s: String) = new String (Array.rev (s.ToCharArray()))
let reversed = rev s1
reversed.CompareTo (rev s2) }
Вы также можете использовать Stroustrup стиль:
let comparer = {
new IComparer<string> with
member x.Compare(s1, s2) =
let rev (s: String) = new String(Array.rev (s.ToCharArray()))
let reversed = rev s1
reversed.CompareTo(rev s2)
}
Пустые определения типов могут быть отформатированы в одной строке:
type AnEmptyType = class end
Независимо от выбранной ширины = class end страницы всегда должно находиться в одной строке.
Форматирование выражений индекса и среза
Выражения индекса не должны содержать пробелы вокруг открывающих и закрывающих квадратных скобок.
// ✔️ OK
let v = expr[idx]
let y = myList[0..1]
// ❌ Not OK
let v = expr[ idx ]
let y = myList[ 0 .. 1 ]
Это также относится к более старым expr.[idx] синтаксисам.
// ✔️ OK
let v = expr.[idx]
let y = myList.[0..1]
// ❌ Not OK
let v = expr.[ idx ]
let y = myList.[ 0 .. 1 ]
Форматирование кавычки выражений
Символы разделителя (<@ , , @>, <@@) @@>должны быть помещены в отдельные строки, если в кавычках есть многострочный выражение.
// ✔️ OK
<@
let f x = x + 10
f 20
@>
// ❌ Not OK
<@ let f x = x + 10
f 20
@>
В однострочных выражениях символы разделителя должны размещаться в той же строке, что и сам выражение.
// ✔️ OK
<@ 1 + 1 @>
// ❌ Not OK
<@
1 + 1
@>
Форматирование цепных выражений
Если цепочка выражений (приложения-функции переплетаются с .) длинна, поместите вызов каждого приложения в следующую строку.
Отступ последующих ссылок в цепочке на один уровень после ведущего канала.
// ✔️ OK
Host
.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(fun webBuilder -> webBuilder.UseStartup<Startup>())
// ✔️ OK
Cli
.Wrap("git")
.WithArguments(arguments)
.WithWorkingDirectory(__SOURCE_DIRECTORY__)
.ExecuteBufferedAsync()
.Task
Ведущая ссылка может быть составлена из нескольких ссылок, если они являются простыми идентификаторами. Например, добавление полного пространства имен.
// ✔️ OK
Microsoft.Extensions.Hosting.Host
.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(fun webBuilder -> webBuilder.UseStartup<Startup>())
Последующие ссылки также должны содержать простые идентификаторы.
// ✔️ OK
configuration.MinimumLevel
.Debug()
// Notice how `.WriteTo` does not need its own line.
.WriteTo.Logger(fun loggerConfiguration ->
loggerConfiguration.Enrich
.WithProperty("host", Environment.MachineName)
.Enrich.WithProperty("user", Environment.UserName)
.Enrich.WithProperty("application", context.HostingEnvironment.ApplicationName))
Если аргументы внутри приложения-функции не помещаются в остальную часть строки, поместите каждый аргумент в следующую строку.
// ✔️ OK
WebHostBuilder()
.UseKestrel()
.UseUrls("http://*:5000/")
.UseCustomCode(
longArgumentOne,
longArgumentTwo,
longArgumentThree,
longArgumentFour
)
.UseContentRoot(Directory.GetCurrentDirectory())
.UseStartup<Startup>()
.Build()
// ✔️ OK
Cache.providedTypes
.GetOrAdd(cacheKey, addCache)
.Value
// ❌ Not OK, formatting tools will reformat to the above
Cache
.providedTypes
.GetOrAdd(
cacheKey,
addCache
)
.Value
Лямбда-аргументы внутри приложения-функции должны начинаться в той же строке, что и открытие (.
// ✔️ OK
builder
.WithEnvironment()
.WithLogger(fun loggerConfiguration ->
// ...
())
// ❌ Not OK, formatting tools will reformat to the above
builder
.WithEnvironment()
.WithLogger(
fun loggerConfiguration ->
// ...
())
Объявления форматирования
В этом разделе рассматриваются объявления форматирования различных типов.
Добавление пустых строк между объявлениями
Разделите определения функций верхнего уровня и классов с одной пустой строкой. Например:
// ✔️ OK
let thing1 = 1+1
let thing2 = 1+2
let thing3 = 1+3
type ThisThat = This | That
// ❌ Not OK
let thing1 = 1+1
let thing2 = 1+2
let thing3 = 1+3
type ThisThat = This | That
Если у конструкции есть комментарии XML-документа, добавьте пустую строку перед комментарием.
// ✔️ OK
/// This is a function
let thisFunction() =
1 + 1
/// This is another function, note the blank line before this line
let thisFunction() =
1 + 1
Форматирование объявлений разрешений и членов
При форматировании let и member объявлениях, как правило, правая сторона привязки либо идет по одной строке, либо (если она слишком длинна) идет на новом отступе одной линии.
Например, следующие примеры соответствуют следующим требованиям:
// ✔️ OK
let a =
"""
foobar, long string
"""
// ✔️ OK
type File =
member this.SaveAsync(path: string) : Async<unit> =
async {
// IO operation
return ()
}
// ✔️ OK
let c =
{ Name = "Bilbo"
Age = 111
Region = "The Shire" }
// ✔️ OK
let d =
while f do
printfn "%A" x
Это не соответствует требованиям:
// ❌ Not OK, code formatters will reformat to the above by default
let a = """
foobar, long string
"""
let d = while f do
printfn "%A" x
Экземпляры типов записей также могут размещать квадратные скобки на собственных строках:
// ✔️ OK
let bilbo =
{
Name = "Bilbo"
Age = 111
Region = "The Shire"
}
Вы также можете использовать Stroustrup стиль, открывая { в той же строке, что и имя привязки:
// ✔️ OK
let bilbo = {
Name = "Bilbo"
Age = 111
Region = "The Shire"
}
Разделите элементы с одной пустой строкой и документом и добавьте комментарий к документации:
// ✔️ OK
/// This is a thing
type ThisThing(value: int) =
/// Gets the value
member _.Value = value
/// Returns twice the value
member _.TwiceValue() = value*2
Для отдельных групп связанных функций можно использовать дополнительные пустые строки (экономно). Пустые строки могут быть пропущены между кучей связанных одностроковых (например, набор фиктивных реализаций). Используйте пустые строки в функциях, разреженно, чтобы указать логические разделы.
Форматирование аргументов функций и элементов
При определении функции используйте пробелы вокруг каждого аргумента.
// ✔️ OK
let myFun (a: decimal) (b: int) c = a + b + c
// ❌ Not OK, code formatters will reformat to the above by default
let myFunBad (a:decimal)(b:int)c = a + b + c
Если у вас есть длинное определение функции, поместите параметры в новые строки и отступ, чтобы они соответствовали уровню отступа последующего параметра.
// ✔️ OK
module M =
let longFunctionWithLotsOfParameters
(aVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse)
=
// ... the body of the method follows
let longFunctionWithLotsOfParametersAndReturnType
(aVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse)
: ReturnType =
// ... the body of the method follows
let longFunctionWithLongTupleParameter
(
aVeryLongParam: AVeryLongTypeThatYouNeedToUse,
aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse,
aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse
) =
// ... the body of the method follows
let longFunctionWithLongTupleParameterAndReturnType
(
aVeryLongParam: AVeryLongTypeThatYouNeedToUse,
aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse,
aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse
) : ReturnType =
// ... the body of the method follows
Это также относится к элементам, конструкторам и параметрам с помощью кортежей:
// ✔️ OK
type TypeWithLongMethod() =
member _.LongMethodWithLotsOfParameters
(
aVeryLongParam: AVeryLongTypeThatYouNeedToUse,
aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse,
aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse
) =
// ... the body of the method
// ✔️ OK
type TypeWithLongConstructor
(
aVeryLongCtorParam: AVeryLongTypeThatYouNeedToUse,
aSecondVeryLongCtorParam: AVeryLongTypeThatYouNeedToUse,
aThirdVeryLongCtorParam: AVeryLongTypeThatYouNeedToUse
) =
// ... the body of the class follows
// ✔️ OK
type TypeWithLongSecondaryConstructor () =
new
(
aVeryLongCtorParam: AVeryLongTypeThatYouNeedToUse,
aSecondVeryLongCtorParam: AVeryLongTypeThatYouNeedToUse,
aThirdVeryLongCtorParam: AVeryLongTypeThatYouNeedToUse
) =
// ... the body of the constructor follows
Если параметры курируются, поместите = символ вместе с любым типом возвращаемого значения в новой строке:
// ✔️ OK
type TypeWithLongCurriedMethods() =
member _.LongMethodWithLotsOfCurriedParamsAndReturnType
(aVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse)
: ReturnType =
// ... the body of the method
member _.LongMethodWithLotsOfCurriedParams
(aVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse)
(aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse)
=
// ... the body of the method
Это способ избежать слишком длинных строк (в случае, если тип возвращаемого значения может иметь длинное имя) и при добавлении параметров меньше повреждения строки.
Объявления операторов форматирования
При необходимости используйте пробелы для окружного определения оператора:
// ✔️ OK
let ( !> ) x f = f x
// ✔️ OK
let (!>) x f = f x
Для любого пользовательского оператора, начинающегося с * нескольких символов, необходимо добавить пробел в начало определения, чтобы избежать неоднозначности компилятора. Из-за этого рекомендуется просто окружить определения всех операторов одним символом пробела.
Форматирование объявлений записей
Для объявлений записей по умолчанию следует отступить { в определении типа по четырем пробелам, запустить список меток в той же строке и выровнять элементы, если таковые есть, с маркером { :
// ✔️ OK
type PostalAddress =
{ Address: string
City: string
Zip: string }
Кроме того, часто рекомендуется помещать квадратные скобки по собственной строке с метками, отступными дополнительными четырьмя пробелами:
// ✔️ OK
type PostalAddress =
{
Address: string
City: string
Zip: string
}
Можно также поместить { в конец первой строки определения типа (Stroustrup стиль):
// ✔️ OK
type PostalAddress = {
Address: string
City: string
Zip: string
}
Если требуются дополнительные члены, не используйте with/end по возможности:
// ✔️ OK
type PostalAddress =
{ Address: string
City: string
Zip: string }
member x.ZipAndCity = $"{x.Zip} {x.City}"
// ❌ Not OK, code formatters will reformat to the above by default
type PostalAddress =
{ Address: string
City: string
Zip: string }
with
member x.ZipAndCity = $"{x.Zip} {x.City}"
end
// ✔️ OK
type PostalAddress =
{
Address: string
City: string
Zip: string
}
member x.ZipAndCity = $"{x.Zip} {x.City}"
// ❌ Not OK, code formatters will reformat to the above by default
type PostalAddress =
{
Address: string
City: string
Zip: string
}
with
member x.ZipAndCity = $"{x.Zip} {x.City}"
end
Исключением из этого правила стиля является форматирование записей в соответствии со стилем Stroustrup . В этой ситуации из-за правил with компилятора ключевое слово требуется, если требуется реализовать интерфейс или добавить дополнительные элементы:
// ✔️ OK
type PostalAddress = {
Address: string
City: string
Zip: string
} with
member x.ZipAndCity = $"{x.Zip} {x.City}"
// ❌ Not OK, this is currently invalid F# code
type PostalAddress = {
Address: string
City: string
Zip: string
}
member x.ZipAndCity = $"{x.Zip} {x.City}"
При добавлении XML-документации для полей Aligned записи или Stroustrup стиля следует добавить дополнительное пространство пробелов между элементами:
// ❌ Not OK - putting { and comments on the same line should be avoided
type PostalAddress =
{ /// The address
Address: string
/// The city
City: string
/// The zip code
Zip: string }
/// Format the zip code and the city
member x.ZipAndCity = $"{x.Zip} {x.City}"
// ✔️ OK
type PostalAddress =
{
/// The address
Address: string
/// The city
City: string
/// The zip code
Zip: string
}
/// Format the zip code and the city
member x.ZipAndCity = $"{x.Zip} {x.City}"
// ✔️ OK - Stroustrup Style
type PostalAddress = {
/// The address
Address: string
/// The city
City: string
/// The zip code
Zip: string
} with
/// Format the zip code and the city
member x.ZipAndCity = $"{x.Zip} {x.City}"
Размещение открытого маркера в новой строке и закрывающего маркера в новой строке предпочтительнее, если вы объявляете реализации или члены интерфейса в записи:
// ✔️ OK
// Declaring additional members on PostalAddress
type PostalAddress =
{
/// The address
Address: string
/// The city
City: string
/// The zip code
Zip: string
}
member x.ZipAndCity = $"{x.Zip} {x.City}"
// ✔️ OK
type MyRecord =
{
/// The record field
SomeField: int
}
interface IMyInterface
Эти же правила применяются к псевдонимам анонимного типа записи.
Форматирование декриминированных объявлений профсоюза
Для объявлений различаемых союзов отступ | в определении типа по четырем пробелам:
// ✔️ OK
type Volume =
| Liter of float
| FluidOunce of float
| ImperialPint of float
// ❌ Not OK
type Volume =
| Liter of float
| USPint of float
| ImperialPint of float
Если есть один короткий союз, вы можете опустить ведущий |.
// ✔️ OK
type Address = Address of string
Для более длинного или многостроного объединения сохраняйте | и помещая каждое поле объединения в новую строку с разделителями * в конце каждой строки.
// ✔️ OK
[<NoEquality; NoComparison>]
type SynBinding =
| SynBinding of
accessibility: SynAccess option *
kind: SynBindingKind *
mustInline: bool *
isMutable: bool *
attributes: SynAttributes *
xmlDoc: PreXmlDoc *
valData: SynValData *
headPat: SynPat *
returnInfo: SynBindingReturnInfo option *
expr: SynExpr *
range: range *
seqPoint: DebugPointAtBinding
При добавлении комментариев документации используйте пустую строку перед каждым /// комментарием.
// ✔️ OK
/// The volume
type Volume =
/// The volume in liters
| Liter of float
/// The volume in fluid ounces
| FluidOunce of float
/// The volume in imperial pints
| ImperialPint of float
Форматирование литеральных объявлений
Литералы F# с помощью атрибута Literal должны размещать атрибут в собственной строке и использовать именование PascalCase:
// ✔️ OK
[<Literal>]
let Path = __SOURCE_DIRECTORY__ + "/" + __SOURCE_FILE__
[<Literal>]
let MyUrl = "www.mywebsitethatiamworkingwith.com"
Избегайте размещения атрибута в той же строке, что и значение.
Форматирование объявлений модуля
Код в локальном модуле должен быть отступен относительно модуля, но код в модуле верхнего уровня не должен быть отступом. Элементы пространства имен не должны быть отступными.
// ✔️ OK - A is a top-level module.
module A
let function1 a b = a - b * b
// ✔️ OK - A1 and A2 are local modules.
module A1 =
let function1 a b = a * a + b * b
module A2 =
let function2 a b = a * a - b * b
Форматирование объявлений do
В объявлениях типов, объявлениях модулей и выражениях вычислений do использование или do! иногда требуется для операций с побочными эффектами.
Если эти диапазоны охватывают несколько строк, используйте отступ и новую строку, чтобы обеспечить согласованность let/let!отступов. Ниже приведен пример использования do в классе:
// ✔️ OK
type Foo() =
let foo =
fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
do
fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
// ❌ Not OK - notice the "do" expression is indented one space less than the `let` expression
type Foo() =
let foo =
fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
do fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
Ниже приведен пример использования do! двух пробелов отступа (так как при do! использовании четырех пробелов отступа нет случайной разницы между подходами при использовании четырех пробелов отступа):
// ✔️ OK
async {
let! foo =
fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
do!
fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
}
// ❌ Not OK - notice the "do!" expression is indented two spaces more than the `let!` expression
async {
let! foo =
fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
do! fooBarBaz
|> loremIpsumDolorSitAmet
|> theQuickBrownFoxJumpedOverTheLazyDog
}
Форматирование операций вычислений
При создании пользовательских операций для выражений вычислений рекомендуется использовать именование верблюдьего Регистра:
// ✔️ OK
type MathBuilder() =
member _.Yield _ = 0
[<CustomOperation("addOne")>]
member _.AddOne (state: int) =
state + 1
[<CustomOperation("subtractOne")>]
member _.SubtractOne (state: int) =
state - 1
[<CustomOperation("divideBy")>]
member _.DivideBy (state: int, divisor: int) =
state / divisor
[<CustomOperation("multiplyBy")>]
member _.MultiplyBy (state: int, factor: int) =
state * factor
let math = MathBuilder()
let myNumber =
math {
addOne
addOne
addOne
subtractOne
divideBy 2
multiplyBy 10
}
Домен, который моделиируется, должен в конечном итоге управлять соглашением об именовании. Если идиоматично использовать другое соглашение, то вместо этого следует использовать это соглашение.
Если возвращаемое значение выражения является вычислительным выражением, предпочесть поместить выражение вычисления ключевое слово имя в собственной строке:
// ✔️ OK
let foo () =
async {
let! value = getValue()
do! somethingElse()
return! anotherOperation value
}
Вы также можете поместить выражение вычисления в ту же строку, что и имя привязки:
// ✔️ OK
let foo () = async {
let! value = getValue()
do! somethingElse()
return! anotherOperation value
}
Независимо от вашего предпочтения, вы должны стремиться оставаться согласованными во всей базе кода. Форматировщики могут позволить указать этот параметр, чтобы оставаться согласованным.
Форматирование типов и заметок типов
В этом разделе рассматриваются типы форматирования и заметки типов. Это включает форматирование файлов подписи с расширением .fsi .
Для типов предпочитать синтаксис префикса для универсальных шаблонов (Foo<T>) с некоторыми конкретными исключениями
F# позволяет писать универсальные типы (например, int list) и стиль префикса (например, list<int>).
Стиль postfix можно использовать только с одним аргументом типа.
Всегда предпочитать стиль .NET, за исключением пяти конкретных типов:
- Для списков F# используйте форму postfix:
int listа неlist<int>. - Для вариантов F# используйте форму постфикса:
int optionа неoption<int>. - Для параметров значения F# используйте форму постфикса:
int voptionа неvoption<int>. - Для массивов F# используйте форму постфикса:
int arrayа неarray<int>.int[] - Для ссылочных ячеек используйте
int refвместоref<int>этого илиRef<int>.
Для всех остальных типов используйте форму префикса.
Типы функций форматирования
При определении сигнатуры функции используйте пробел вокруг символа -> :
// ✔️ OK
type MyFun = int -> int -> string
// ❌ Not OK
type MyFunBad = int->int->string
Заметки о форматировании значений и типов аргументов
При определении значений или аргументов с заметками типа используйте пробел после символа : , но не раньше:
// ✔️ OK
let complexFunction (a: int) (b: int) c = a + b + c
let simpleValue: int = 0 // Type annotation for let-bound value
type C() =
member _.Property: int = 1
// ❌ Not OK
let complexFunctionPoorlyAnnotated (a :int) (b :int) (c:int) = a + b + c
let simpleValuePoorlyAnnotated1:int = 1
let simpleValuePoorlyAnnotated2 :int = 2
Форматирование заметок многострого типа
Если заметка типа длинна или многострочный, поместите их на следующую строку с отступом на один уровень.
type ExprFolder<'State> =
{ exprIntercept:
('State -> Expr -> 'State) -> ('State -> Expr -> 'State -> 'State -> Exp -> 'State }
let UpdateUI
(model:
#if NETCOREAPP2_1
ITreeModel
#else
TreeModel
#endif
)
(info: FileInfo) =
// code
()
let f
(x:
{|
a: Second
b: Metre
c: Kilogram
d: Ampere
e: Kelvin
f: Mole
g: Candela
|})
=
x.a
type Sample
(
input:
LongTupleItemTypeOneThing *
LongTupleItemTypeThingTwo *
LongTupleItemTypeThree *
LongThingFour *
LongThingFiveYow
) =
class
end
Для встроенных анонимных типов записей можно также использовать Stroustrup стиль:
let f
(x: {|
x: int
y: AReallyLongTypeThatIsMuchLongerThan40Characters
|})
=
x
Форматирование заметок возвращаемого типа
В заметках возвращаемого типа функции или члена используйте пробел до и после символа : :
// ✔️ OK
let myFun (a: decimal) b c : decimal = a + b + c
type C() =
member _.SomeMethod(x: int) : int = 1
// ❌ Not OK
let myFunBad (a: decimal) b c:decimal = a + b + c
let anotherFunBad (arg: int): unit = ()
type C() =
member _.SomeMethodBad(x: int): int = 1
Форматирование типов в сигнатурах
При написании полных типов функций в сигнатурах иногда необходимо разделить аргументы по нескольким строкам. Возвращаемый тип всегда отступен.
Для кортежной функции аргументы разделяются *по концам каждой строки.
Например, рассмотрим функцию со следующей реализацией:
let SampleTupledFunction(arg1, arg2, arg3, arg4) = ...
В соответствующем файле подписи (.fsi расширение) функция может быть отформатирована следующим образом, если требуется многострочный формат:
// ✔️ OK
val SampleTupledFunction:
arg1: string *
arg2: string *
arg3: int *
arg4: int ->
int list
Аналогичным образом рассмотрим курированную функцию:
let SampleCurriedFunction arg1 arg2 arg3 arg4 = ...
В соответствующем файле -> сигнатуры помещаются в конец каждой строки:
// ✔️ OK
val SampleCurriedFunction:
arg1: string ->
arg2: string ->
arg3: int ->
arg4: int ->
int list
Аналогичным образом рассмотрим функцию, которая принимает сочетание курриированных и кортежных аргументов:
// Typical call syntax:
let SampleMixedFunction
(arg1, arg2)
(arg3, arg4, arg5)
(arg6, arg7)
(arg8, arg9, arg10) = ..
В соответствующем файле сигнатуры типы, предшествующие кортежу, отступят
// ✔️ OK
val SampleMixedFunction:
arg1: string *
arg2: string ->
arg3: string *
arg4: string *
arg5: TType ->
arg6: TType *
arg7: TType ->
arg8: TType *
arg9: TType *
arg10: TType ->
TType list
Те же правила применяются для членов в сигнатурах типов:
type SampleTypeName =
member ResolveDependencies:
arg1: string *
arg2: string ->
string
Форматирование явных аргументов универсального типа и ограничений
Приведенные ниже рекомендации применяются к определениям функций, определениям элементов, определениям типов и приложениям-функциям.
Сохраняйте аргументы и ограничения универсального типа в одной строке, если она не слишком длинна:
// ✔️ OK
let f<'T1, 'T2 when 'T1: equality and 'T2: comparison> param =
// function body
Если аргументы или ограничения универсального типа и параметры функции не соответствуют, но параметры типа и ограничения выполняются отдельно, поместите параметры в новые строки:
// ✔️ OK
let f<'T1, 'T2 when 'T1: equality and 'T2: comparison>
param
=
// function body
Если параметры или ограничения типа слишком длинны, разорвать и выравнивать их, как показано ниже. Сохраняйте список параметров типа в той же строке, что и функция, независимо от его длины. Для ограничений следует поместить when в первую строку и сохранить каждое ограничение на одной строке независимо от его длины. Поместите > в конце последней строки. Отступ ограничений на один уровень.
// ✔️ OK
let inline f< ^T1, ^T2
when ^T1: (static member Foo1: unit -> ^T2)
and ^T2: (member Foo2: unit -> int)
and ^T2: (member Foo3: string -> ^T1 option)>
arg1
arg2
=
// function body
Если параметры и ограничения типа разбиты, но нет нормальных параметров функции, поместите = его в новую строку независимо от следующего:
// ✔️ OK
let inline f< ^T1, ^T2
when ^T1: (static member Foo1: unit -> ^T2)
and ^T2: (member Foo2: unit -> int)
and ^T2: (member Foo3: string -> ^T1 option)>
=
// function body
Те же правила применяются к приложениям-функциям:
// ✔️ OK
myObj
|> Json.serialize<
{| child: {| displayName: string; kind: string |}
newParent: {| id: string; displayName: string |}
requiresApproval: bool |}>
// ✔️ OK
Json.serialize<
{| child: {| displayName: string; kind: string |}
newParent: {| id: string; displayName: string |}
requiresApproval: bool |}>
myObj
Наследование форматирования
Аргументы конструктора базового класса отображаются в списке аргументов в предложении inherit .
inherit Поместите предложение на новую строку с отступом на один уровень.
type MyClassBase(x: int) =
class
end
// ✔️ OK
type MyClassDerived(y: int) =
inherit MyClassBase(y * 2)
// ❌ Not OK
type MyClassDerived(y: int) = inherit MyClassBase(y * 2)
Если конструктор длинный или многострочный, поместите их на следующую строку с отступом на один уровень.
Отформатируйте этот многостроевой конструктор в соответствии с правилами многостроковых приложений-функций.
type MyClassBase(x: string) =
class
end
// ✔️ OK
type MyClassDerived(y: string) =
inherit
MyClassBase(
"""
very long
string example
"""
)
// ❌ Not OK
type MyClassDerived(y: string) =
inherit MyClassBase(
"""
very long
string example
""")
Форматирование основного конструктора
В соглашениях о форматировании по умолчанию пробелы не добавляются между именем типа и скобками для основного конструктора.
// ✔️ OK
type MyClass() =
class
end
type MyClassWithParams(x: int, y: int) =
class
end
// ❌ Not OK
type MyClass () =
class
end
type MyClassWithParams (x: int, y: int) =
class
end
Несколько конструкторов
inherit Если предложение является частью записи, поместите его в ту же строку, если она коротка.
И положите его на следующую строку, отступ на один уровень, если он длинный или многострочный.
type BaseClass =
val string1: string
new () = { string1 = "" }
new (str) = { string1 = str }
type DerivedClass =
inherit BaseClass
val string2: string
new (str1, str2) = { inherit BaseClass(str1); string2 = str2 }
new () =
{ inherit
BaseClass(
"""
very long
string example
"""
)
string2 = str2 }
Атрибуты форматирования
Атрибуты помещаются над конструкцией:
// ✔️ OK
[<SomeAttribute>]
type MyClass() = ...
// ✔️ OK
[<RequireQualifiedAccess>]
module M =
let f x = x
// ✔️ OK
[<Struct>]
type MyRecord =
{ Label1: int
Label2: string }
Они должны идти после любой XML-документации:
// ✔️ OK
/// Module with some things in it.
[<RequireQualifiedAccess>]
module M =
let f x = x
Форматирование атрибутов параметров
Атрибуты также можно поместить в параметры. В этом случае поместите в ту же строку, что и параметр, и перед именем:
// ✔️ OK - defines a class that takes an optional value as input defaulting to false.
type C() =
member _.M([<Optional; DefaultParameterValue(false)>] doSomething: bool)
Форматирование нескольких атрибутов
При применении нескольких атрибутов к конструкции, которая не является параметром, поместите каждый атрибут в отдельную строку:
// ✔️ OK
[<Struct>]
[<IsByRefLike>]
type MyRecord =
{ Label1: int
Label2: string }
При применении к параметру поместите атрибуты в одну строку и разделите их разделителем ; .
Благодарности
Эти рекомендации основаны на комплексном руководстве по соглашению о форматировании F# Anh-Dung Phan.
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по