Merge pull request #231 from onflow/control-flow-scope

Edit Control Flow and Scope articles

Author: briandoyle81

docs/language/control-flow.md

@@ -9,12 +9,11 @@ Control flow statements control the flow of execution in a function.
 
 If-statements allow a certain piece of code to be executed only when a given condition is true.
 
-The if-statement starts with the `if` keyword, followed by the condition,
-and the code that should be executed if the condition is true
-inside opening and closing braces.
-The condition expression must be boolean.
-The braces are required and not optional.
-Parentheses around the condition are optional.
+The if-statement starts with the `if` keyword, followed by the condition, and the code that should be executed if the condition is true, inside opening and closing braces.
+
+- The condition expression must be a boolean.
+- The braces are required and not optional.
+- Parentheses around the condition are optional:
 
 ```cadence
 let a = 0
@@ -32,10 +31,7 @@ if (a != 0) {
 // `b` is `1`
 ```
 
-An additional, optional else-clause can be added to execute another piece of code
-when the condition is false.
-The else-clause is introduced by the `else` keyword followed by braces
-that contain the code that should be executed.
+An additional, optional else-clause can be added to execute another piece of code when the condition is false. The else-clause is introduced by the `else` keyword, followed by braces that contain the code that should be executed:
 
 ```cadence
 let a = 0
@@ -50,8 +46,7 @@ if a == 1 {
 // `b` is `2`
 ```
 
-The else-clause can contain another if-statement, i.e., if-statements can be chained together.
-In this case the braces can be omitted.
+The else-clause can contain another if-statement (i.e., if-statements can be chained together). In this case, the braces can be omitted:
 
 ```cadence
 let a = 0
@@ -78,19 +73,13 @@ if a == 1 {
 // `b` is `2`
 ```
 
-## Optional Binding
+## Optional binding
 
-Optional binding allows getting the value inside an optional.
-It is a variant of the if-statement.
+Optional binding allows getting the value inside an optional. It is a variant of the if-statement.
 
-If the optional contains a value, the first branch is executed
-and a temporary constant or variable is declared and set to the value contained in the optional;
-otherwise, the else branch (if any) is executed.
+If the optional contains a value, the first branch is executed and a temporary constant or variable is declared and set to the value contained in the optional; otherwise, the else branch (if any) is executed.
 
-Optional bindings are declared using the `if` keyword like an if-statement,
-but instead of the boolean test value, it is followed by the `let` or `var` keywords,
-to either introduce a constant or variable, followed by a name,
-the equal sign (`=`), and the optional value.
+Optional bindings are declared using the `if` keyword like an if-statement, but instead of the boolean test value, it is followed by the `let` or `var` keywords, to either introduce a constant or variable, followed by a name, the equal sign (`=`), and the optional value:
 
 ```cadence
 let maybeNumber: Int? = 1
@@ -116,29 +105,15 @@ if let number = noNumber {
 
 ## Switch
 
-Switch-statements compare a value against several possible values of the same type, in order.
-When an equal value is found, the associated block of code is executed.
+Switch-statements compare a value against several possible values of the same type, in order. When an equal value is found, the associated block of code is executed.
 
-The switch-statement starts with the `switch` keyword, followed by the tested value,
-followed by the cases inside opening and closing braces.
-The test expression must be equatable.
-The braces are required and not optional.
+The switch-statement starts with the `switch` keyword, followed by the tested value, followed by the cases inside opening and closing braces. The test expression must be equatable. The braces are required and not optional.
 
-Each case is a separate branch of code execution
-and starts with the `case` keyword,
-followed by a possible value, a colon (`:`),
-and the block of code that should be executed
-if the case's value is equal to the tested value.
+Each case is a separate branch of code execution and starts with the `case` keyword, followed by a possible value, a colon (`:`), and the block of code that should be executed if the case's value is equal to the tested value.
 
-The block of code associated with a switch case
-[does not implicitly fall through](#no-implicit-fallthrough),
-and must contain at least one statement.
-Empty blocks are invalid.
+The block of code associated with a switch case [does not implicitly fall through], and must contain at least one statement. Empty blocks are invalid.
 
-An optional default case may be given by using the `default` keyword.
-The block of code of the default case is executed
-when none of the previous case tests succeeded.
-It must always appear last.
+An optional default case may be given by using the `default` keyword. The block of code of the default case is executed when none of the previous case tests succeed. It must always appear last:
 
 ```cadence
 fun word(_ n: Int): String {
@@ -167,8 +142,7 @@ word(4)  // returns "other"
 
 ### Duplicate cases
 
-Cases are tested in order, so if a case is duplicated,
-the block of code associated with the first case that succeeds is executed.
+Cases are tested in order, so if a case is duplicated, the block of code associated with the first case that succeeds is executed:
 
 ```cadence
 fun test(_ n: Int): String {
@@ -195,29 +169,17 @@ word(1) // returns "one", not "also one"
 
 ### `break`
 
-The block of code associated with a switch case may contain a `break` statement.
-It ends the execution of the switch statement immediately
-and transfers control to the code after the switch statement
+The block of code associated with a switch case may contain a `break` statement. It ends the execution of the switch statement immediately and transfers control to the code after the switch statement.
 
-### No Implicit Fallthrough
+### No implicit fallthrough
 
-Unlike switch statements in some other languages,
-switch statements in Cadence do not "fall through":
-execution of the switch statement finishes as soon as the block of code
-associated with the first matching case is completed.
-No explicit `break` statement is required.
+Unlike switch statements in some other languages, switch statements in Cadence do not _fall through_: execution of the switch statement finishes as soon as the block of code associated with the first matching case is completed. No explicit `break` statement is required.
 
-This makes the switch statement safer and easier to use,
-avoiding the accidental execution of more than one switch case.
+This makes the switch statement safer and easier to use, avoiding the accidental execution of more than one switch case.
 
-Some other languages implicitly fall through
-to the block of code associated with the next case,
-so it is common to write cases with an empty block
-to handle multiple values in the same way.
+Some other languages implicitly fall through to the block of code associated with the next case, so it is common to write cases with an empty block to handle multiple values in the same way.
 
-To prevent developers from writing switch statements
-that assume this behaviour, blocks must have at least one statement.
-Empty blocks are invalid.
+To protect developers from writing switch statements that assume this behavior, blocks must have at least one statement. Empty blocks are invalid:
 
 ```cadence
 fun words(_ n: Int): [String] {
@@ -251,21 +213,15 @@ words(4)  // returns `["other"]`
 
 ## Looping
 
+The following sections describe looping statements.
+
 ### while-statement
 
-While-statements allow a certain piece of code to be executed repeatedly,
-as long as a condition remains true.
+While-statements allow a certain piece of code to be executed repeatedly, as long as a condition remains true.
 
-The while-statement starts with the `while` keyword, followed by the condition,
-and the code that should be repeatedly
-executed if the condition is true inside opening and closing braces.
-The condition must be boolean and the braces are required.
+The while-statement starts with the `while` keyword, followed by the condition, and the code that should be repeatedly executed if the condition is true inside opening and closing braces. The condition must be boolean, and the braces are required.
 
-The while-statement will first evaluate the condition.
-If it is true, the piece of code is executed and the evaluation of the condition is repeated.
-If the condition is false, the piece of code is not executed
-and the execution of the whole while-statement is finished.
-Thus, the piece of code is executed zero or more times.
+The while-statement will first evaluate the condition. If it is true, the piece of code is executed, and the evaluation of the condition is repeated. If the condition is false, the piece of code is not executed, and the execution of the whole while-statement is finished. Thus, the piece of code is executed zero or more times:
 
 ```cadence
 var a = 0
@@ -278,20 +234,13 @@ while a < 5 {
 
 ### For-in statement
 
-For-in statements allow a certain piece of code to be executed repeatedly for
-each element in an array.
+For-in statements allow a certain piece of code to be executed repeatedly for each element in an array.
 
-The for-in statement starts with the `for` keyword, followed by the name of
-the element that is used in each iteration of the loop,
-followed by the `in` keyword, and then followed by the array
-that is being iterated through in the loop.
+The for-in statement starts with the `for` keyword, followed by the name of the element that is used in each iteration of the loop, followed by the `in` keyword, and then followed by the array that is being iterated through in the loop.
 
-Then, the code that should be repeatedly executed in each iteration of the loop
-is enclosed in curly braces.
+Then, the code that should be repeatedly executed in each iteration of the loop is enclosed in curly braces.
 
-If there are no elements in the data structure, the code in the loop will not
-be executed at all. Otherwise, the code will execute as many times
-as there are elements in the array.
+If there are no elements in the data structure, the code in the loop will not be executed at all. Otherwise, the code will execute as many times as there are elements in the array:
 
 ```cadence
 let array = ["Hello", "World", "Foo", "Bar"]
@@ -307,11 +256,7 @@ for element in array {
 // "Bar"
 ```
 
-Optionally, developers may include an additional variable preceding the element name,
-separated by a comma.
-When present, this variable contains the current
-index of the array being iterated through
-during each repeated execution (starting from 0).
+Optionally, developers may include an additional variable preceding the element name, separated by a comma. When present, this variable contains the current index of the array being iterated through during each repeated execution (starting from 0):
 
 ```cadence
 let array = ["Hello", "World", "Foo", "Bar"]
@@ -327,8 +272,7 @@ for index, element in array {
 // 3
 ```
 
-To iterate over a dictionary's entries (keys and values),
-use a for-in loop over the dictionary's keys and get the value for each key:
+To iterate over a dictionary's entries (keys and values), use a for-in loop over the dictionary's keys and get the value for each key:
 
 ```cadence
 let dictionary = {"one": 1, "two": 2}
@@ -358,10 +302,9 @@ dictionary.forEachKey(fun (key: String): Bool {
 })
 ```
 
-### Ranges in Loops
+### Ranges in loops
 
-An [`InclusiveRange` value](./values-and-types/inclusive-range.md) can be used in a for-in statement in place of an array or dictionary. In this case, 
-the loop will iterate over all the values contained in the range, beginning with `range.start` and ending with `range.end`. E.g. 
+An [`InclusiveRange` value] can be used in a for-in statement in place of an array or dictionary. In this case, the loop will iterate over all the values contained in the range, beginning with `range.start` and ending with `range.end`. For example:
 
 ```cadence
 let range: InclusiveRange<UInt> = InclusiveRange(1, 100, step: 2)
@@ -419,8 +362,7 @@ while range.contains(index) {
 
 ### `continue` and `break`
 
-In for-loops and while-loops, the `continue` statement can be used to stop
-the current iteration of a loop and start the next iteration.
+In for-loops and while-loops, the `continue` statement can be used to stop the current iteration of a loop and start the next iteration:
 
 ```cadence
 var i = 0
@@ -448,8 +390,7 @@ for element in array {
 
 ```
 
-The `break` statement can be used to stop the execution
-of a for-loop or a while-loop.
+The `break` statement can be used to stop the execution of a for-loop or a while-loop:
 
 ```cadence
 var x = 0
@@ -476,7 +417,9 @@ for element in array {
 
 ## Immediate function return: return-statement
 
-The return-statement causes a function to return immediately,
-i.e., any code after the return-statement is not executed.
-The return-statement starts with the `return` keyword
-and is followed by an optional expression that should be the return value of the function call.
+The return-statement causes a function to return immediately (i.e., any code after the return-statement is not executed). The return-statement starts with the `return` keyword and is followed by an optional expression that should be the return value of the function call.
+
+<!-- Relative links. Will not render on the page -->
+
+[does not implicitly fall through]: #no-implicit-fallthrough
+[`InclusiveRange` value]: ./values-and-types/inclusive-range.md

docs/language/scope.md

@@ -3,8 +3,7 @@ title: Scope
 sidebar_position: 8
 ---
 
-Every function and block (`{` ... `}`) introduces a new scope for declarations.
-Each function and block can refer to declarations in its scope or any of the outer scopes.
+Every function and block (`{` ... `}`) introduces a new scope for declarations. Each function and block can refer to declarations in its scope or any of the outer scopes:
 
 ```cadence
 let x = 10
@@ -34,7 +33,7 @@ fun doubleAndAddOne(_ n: Int): Int {
 double(1)
 ```
 
-Each scope can introduce new declarations, i.e., the outer declaration is shadowed.
+Each scope can introduce new declarations (i.e., the outer declaration is shadowed):
 
 ```cadence
 let x = 2
@@ -47,7 +46,7 @@ fun test(): Int {
 test()  // is `3`
 ```
 
-Scope is lexical, not dynamic.
+Scope is lexical, not dynamic:
 
 ```cadence
 let x = 10
@@ -64,7 +63,7 @@ fun g(): Int {
 g()  // is `10`, not `20`
 ```
 
-Declarations are **not** moved to the top of the enclosing function (hoisted).
+Declarations are **not** moved to the top of the enclosing function (hoisted):
 
 ```cadence
 let x = 2