sort out sequence and data concepts

Author: macite

src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/00-program.md

@@ -89,7 +89,7 @@ We use data to capture the information we need the program to work with. The dat
 :::note[Summary]
 
 - You can create something the user can run from the program's **source code**.
-- Most importantly, you cant really *see* the program in the code. The program is **all** of this code together. It is the container that holds the instructions that will run when it is executed.
+- Most importantly, you can't really *see* the program in the code. The program is **all** of this code together. It is the container that holds the instructions that will run when it is executed.
 - The program has an **entry point** that indicates where the program’s instructions start - in this case the first instruction.
 - Your program can use code from [libraries](../08-library) giving it access to building blocks others have created.
 - Data is also central to the program.

src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/03-method-call.md

@@ -101,22 +101,22 @@ All of the arguments in this code are using literal values.
 
 ### Example using result
 
-Some methods return data, which you can use within any calculated value ([expression](../07-expression)) within your code. The following code demonstrates the use of the values returned by the `ColorWhite` and `Rnd` methods.
+Some methods return data, which you can use within any calculated value ([expression](../07-expression)) within your code. The following code demonstrates the use of the values returned by the `RandomColor` and `Rnd` methods.
 
 <a id="ListingReturn"></a>
 
 ```csharp
 using static SplashKitSDK.SplashKit;
 
-OpenWindow("A House", 800, 600);
-ClearScreen(ColorWhite());
+OpenWindow("Random Color", 800, 600);
+ClearScreen(RandomColor());
 RefreshScreen();
 Delay(1000 * Rnd(10));
 ```
 
 <div class="caption"><span class="caption-figure-nbr">Listing 5.x: </span>Code demonstrating use of return values.</div>
 
-Line 4 demonstrates the use of the result from calling `ColorWhite` within the call to `ClearScreen`. In this case, the value returned from the `ColorWhite` becomes the value for the argument passed to `ClearScreen`. As you would expect, this will clear the screen to the white color.
+Line 4 demonstrates the use of the result from calling `RandomColor` within the call to `ClearScreen`. In this case, the value returned from the `RandomColor` becomes the value for the argument passed to `ClearScreen`. As you would expect, this will clear the screen to a random color.
 
 Line 6 demonstrates this again, the result of `1000 * Rnd(10)` is passed to `Delay`. The easiest way to approach this is to consider each value independently. `Rnd(10)` will return a random value between 0 and 10 - let us imagine this returns `6` so that we can see what that does. In this case, `1000 * Rnd(10)` becomes `1000 * 6`, as the value **returned** by `Rnd(10)` was `6`. This is then evaluated, and `Delay` will be passed the argument `6000`, causing it to delay for 6 seconds.
 

src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/19-assignment-statement.md renamed to src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/09-assignment-statement.md

@@ -1,3 +1,4 @@
 ---
 title: Sequence
 ---
+

src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/10-comments.md

@@ -0,0 +1,85 @@
+---
+title: "Comments"
+---
+
+A program's source code contains instructions for the computer to perform. However, this code is written and maintained by people. It is often useful to be able to place comments in the code to help someone reading that code understand how it works or what it is trying to achieve. This text is not something to be translated into machine code, it is for us humans.
+
+Programming languages support the ability to embed *comments* into the source code that are then ignored by the compiler.
+
+## In C#
+As stated, comments allow you to embed documentation and explanatory text within your program’s code. The comments are skipped by the compiler, so they have no affect on the program’s machine code. You write comments to help yourself and other people understand what you intend the program to do, and any thoughts you want to record along with the code.
+
+
+:::tip[Syntax]
+
+<a href="#FigureCommentsSyntax">Figure 5.13</a> shows the syntax for comments in C#. There are two types of comments, single line comments, and block comments that span multiple lines.
+
+- **Block comments** begin with `/*` and end with `*/` and contain any text in between these, including new lines.
+- **Single line comment** begin with `//` and end with a new line.
+
+
+<a id="FigureCommentsSyntax"></a>
+
+![Figure 5.13 The syntax of comments.](./images/program-creation/CommentsSyntax.png "The syntax of comments")
+<div class="caption"><span class="caption-figure-nbr">Figure 5.13: </span>The syntax of comments</div><br/>
+
+:::
+
+## Example
+
+Example comments are shown within a code block in <a href="#ListingExampleComments">Listing 5.11</a> below</div>
+
+<a id="ListingExampleComments"></a>
+
+```csharp
+/* 
+ * This program calculates the area of a circle based on the radius. 
+ * Variables:
+ *  - the radius as a double
+ *  - the area as a double
+ *  - a line string to read text from the user
+ */
+
+using static System.Convert;
+using static System.Console;
+
+// Setup constants and variables
+const double PI = 3.1415;
+string line;
+double radius, area;
+
+// Get data from the user
+Write("Radius: ");
+line = ReadLine();
+radius = ToDouble(line);
+
+// Calculate area
+area = PI * radius * radius;
+
+// Output area
+WriteLine(area);
+```
+
+<div class="caption"><span class="caption-figure-nbr">Listing 5.11: </span>Example C# comments</div>
+
+
+## Activities
+
+1. Is the following a valid comment in C#? Why/why not?
+
+```csharp
+/* 
+  /* my comment */ 
+*/
+```
+
+<div class="caption"><span class="caption-figure-nbr">Listing 5.12: </span>Sample code</div>
+
+:::note[Summary]
+
+- It is good practice to place a comment at the top of your code explaining what the program does.
+- Comments should be included to help other people read your code. You will also find these comments useful when you return to your code after a long break.
+- Make your comments meaningful by trying to capture your intentions and ideas
+- Comments have no impact on the output produced by the compiler.
+
+:::

src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/09-sequence.md renamed to src/content/docs/book/part-1-instructions/1-sequence-and-data/1-concepts/10-sequence.md

@@ -1,5 +1,5 @@
 ---
-title: "Summary of Program Creation Concepts"
+title: "Summary"
 type: "content"
 date: 2023-08-07 16:45:00
 draft: false