Stage 0: Adjusted from feedback

examples/stage0/snippets/src/JavaFundamentals.java

@@ -3,10 +3,13 @@
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
+int matchTime = 0;
+
 // [variables]
-int CLIMBER_ID = 51;
-double UP_POSITION = -33.5;
-double DOWN_POSITION = 0;
+int CLIMBER_ID = 51; // an integer named CLIMBER_ID that holds the value 51
+double UP_POSITION = 33.5; // a double named UP_POSITION that holds the value 33.5
+boolean isFinished = false; // a boolean named isFinished that holds the value false
+String autoName = "Side Auto"; // a String named "autoName" that holds the value "Side Auto"
 // [/variables]
 
 void main() {
@@ -15,8 +18,8 @@ void main() {
     // [/printLiteral]
 
     // [printVariable]
-    int number = 4;
-    System.out.println(number); // prints out the value 4
+    int num = 4;
+    System.out.println(num); // prints out the value 4
     // [/printVariable]
 
     // [singleLineComment]
@@ -33,4 +36,14 @@ void main() {
     This is another line */
     System.out.println("Hello World");
     // [/multiLineComment]
+
+    // [goodComment]
+    // Calculate how long is left in the match and show it to the drivers
+    System.out.println(150 - matchTime);
+    // [/goodComment]
+
+    // [badComment]
+    // Print 150 minus matchTime
+    System.out.println(150 - matchTime);
+    // [/badComment]
 }

examples/stage0/snippets/src/Operators.java

@@ -10,11 +10,6 @@
 // [/variables]
 
 void main() {
-    // [multiplication]
-    int magicNumber = 6;
-    System.out.println(magicNumber * 2);
-    // [/multiplication]
-
     // [increments]
     int x = 6;
     int y = 7;
@@ -50,4 +45,17 @@ void main() {
     System.out.println(fiveIsGreaterThanThree || nineIsLessThanTwo);
     System.out.println(!fiveIsGreaterThanThree);
     // [/logical]
+
+
+    // [math1]
+    int e = 0;
+    int f = 2;
+    System.out.println(e = f + 10);
+    // [/math1]
+
+    // [math2]
+    int magicNumber = 6;
+    System.out.println(magicNumber * 2);
+    // [/math2]
+
 }

src/content/docs/learning-course/stage0/conditionals.mdx

@@ -8,9 +8,9 @@ codeRegionSources:
 ---
 
 In everyday life, we make decisions based on different situations.
-Such as "If we are hungry, then we get a snack" or "If we are tired, we go to bed".
-Often in code, we want our program to do something similar and make different decisions based on different situations.
-When programming a robot, one example could be "If the timer starts, drive the robot for 5 seconds then stop when the timer reached 15 seconds.
+For example, "If we are hungry, then we get a snack" or "If we are tired, we go to bed."
+Robots often need to make different decisions based on different situations.
+For example, "If the timer starts, drive the robot for 5 seconds" or "If the timer is 0, stop driving."
 To add decisions to our code, we use conditionals.
 
 This section will cover three types of conditionals which are:
@@ -26,14 +26,9 @@ This section will cover three types of conditionals which are:
     conditional.](https://www.w3schools.com/java/java_switch.asp)
 </Aside>
 
-Like we mentioned earlier in [Java Fundamentals](/learning-course/stage0/java-fundamentals/), all programming languages have syntax that needs to be followed.
-One part of syntax is keywords.
-As a reminder, a keyword is a reserved word that the compiler uses to run the code.
-In Java, we use the following keywords for conditionals: `if`, `else if`, `else`
-
 ## if
 
-An `if` statement is a basic conditional.
+An `if` statement runs code only if a specified condition is true.
 The syntax for an `if` statement is as follows:
 
 ```java #ifSyntax
@@ -48,8 +43,8 @@ Let's break down what this means:
 - `{` an open curly braces is used to denote the opening of the conditional
 - `}` a closed curly braces is used to denote the end of the conditional
 
-The code in between the opening and closing curly braces are called a "code block".
-A code block a sequence of code that is enclosed in curly braces.
+The code in between the opening and closing curly braces is called a "code block".
+A code block a code block is a sequence of code.
 
 <Aside type="tip">
     All conditionals follow a very similar syntax. They all start with a
@@ -60,26 +55,15 @@ A code block a sequence of code that is enclosed in curly braces.
 `if` statements can make decisions based on the `condition` inside the parentheses.
 If `condition` is true, the code inside the `if` block will run.
 If `condition` is false, the code inside the `if` block will be skipped.
-This is also described in the flowchart below
-
-<ContentFigure
-    src="/learning-course/stage0/conditionals/ifstatement.webp"
-    width="400px"
-    height="800px"
-/>
 
 Now let's look at an example.
-In this example, pretend that we have a robot with a distance sensor on it.
-A distance sensor detects and reports how far or how close the robot is to an object.
-We want our robot's drivetrain motors to keep spinning until the robot is 10cm away from an object.
-Our robot is currently 6cm away.
-Looking at the example below, what should happen?
+In this example, this code will move forward only when distance is smaller then 10.
 
 ```java #ifExample
 
 ```
 
-The condition is `distance < 10`.
+This works because the condition is `distance < 10`.
 We know `distance` is equal to 6, therefore we can think of the condition saying 6 < 10. 6 is less than 10 which makes the condition true.
 This means the code inside the `if` block runs, which prints "Motors are spinning" and the spins the motors at full speed.
 
@@ -100,15 +84,8 @@ The syntax for an else statement is as follows:
 Here's how this works: if the`if` statement's condition is `true`, then the code inside will run.
 If the `if` statement's condition is `false`, the `if` block will be skipped, and the code inside the `else` block will run.
 
-This is also described in the flowchart below
-
-<ContentFigure
-    src="/learning-course/stage0/conditionals/else.webp"
-    width="600px"
-    height="800px"
-/>
-
-In this example, we now have an `else` statement that sets the motor speed to 0 if `distance` is greater than 20. Since our `distance` is set to 21, what would the code print out?
+In this example, we now have an `else` statement that sets the motor speed to 0 if `distance` is greater than 20.
+Since our `distance` is set to 21, what would the code print out?
 
 ```java #elseExample
 
@@ -120,10 +97,8 @@ The `else` runs and it prints out "Motors are not spinning", and the motors are
 
 ## else if
 
-Sometimes we want our code to have specific logic for multiple cases.
-Often we want the robot to slow down as it approaches its target.
-Let's say we want the robot to drive at half speed when it's 5cm away from its target.
-This can be done by adding an `else if` statement.
+`if` and `else` lets you choose between two options, but what if you wanted to choose between even more options?
+An `else if` statement let you choose between as many conditions as you like.
 
 The syntax for an `else if` statement goes as follows:
 
@@ -139,13 +114,6 @@ If `conditionA` is true then the code inside the `if` block will run.
 If `conditionA` if false, then it will go to the `else if` statement.
 If `conditionB` is true, the code inside the `else if` block will run.
 If `conditionB` if false, then it will exit the statement and none of the code will run.
-This is also described in the flowchart below
-
-<ContentFigure
-    src="/learning-course/stage0/conditionals/elseif.webp"
-    width="700px"
-    height="800px"
-/>
 
 In the example, we now have an `else if` statement that sets the motor to half speed if the distance from an object is less than 10cm.
 Our `distance` is now 15cm.

src/content/docs/learning-course/stage0/java-fundamentals.mdx

@@ -9,41 +9,31 @@ codeRegionSources:
 
 ## Syntax
 
-As you start programming, you might make a mistake or make a typo.
-When that happens, your code will have a red line under it.
-This is because Java has rules called syntax.
-Syntax is a set of rules that have to be followed so that the computer can understand and run your code.
-It’s important to pay attention to the syntax!
-If your code has a red line under it, first check whether the syntax is correct.
-This can be done by researching online or by comparing your code with examples.
-
-You can also learn what’s wrong with your code when you put the cursor over the section of the code with the red line and read what the error message is.
-Error messages will not tell you exactly what's wrong with your code.
-If you’re unsure on what the error message means, you can look it up to get additional context.
-
-<Slides>
-![Slide 1](/learning-course/stage0/java-fundamentals/ErrorExample1.webp) An example of a syntax error (note the squiggly line)
-
-![Slide 2](/learning-course/stage0/java-fundamentals/ErrorExample2.webp) An example of a syntax error popup
-
-</Slides>
+Syntax is the basic set of rules that all programs in a language must follow.
+Java's syntax is very specific, there are different rules for how certain lines of code are written.
+Syntax errors are the most common sorts of errors.
+Whenever the syntax is mentioned, pay attention closely.
 
 ## Variables
 
 Variables are containers that are used to store information in a program.
 This could be a variable that holds the temperature or a variable that holds the speed of the motor.
 
-Variable declarations have the following syntax:
+To make a variable, there are 5 parts:
 
-{/* rli:ignore */}
+1. Data type
+2. Name of the variable
+3. Equals sign
+4. Value
+5. Semi-colon
 
-```java
-Datatype name = value;
-```
+### Data Types
 
 Data types refer to the type of value that our variable has.
 It helps tell our program more information about our variables such as what type of information it holds and how it can be used.
-Data types can include numbers, characters, or a string of words.
+Unlike many programming languages like Python, in Java, you must specify the type of every variable.
+This makes your programs more reliable, because the compiler will prevent you from using the wrong type with an error.
+
 Some example data types that are commonly used in FRC programming are:
 
 - int: Integer numbers that are positive or negative.
@@ -56,16 +46,22 @@ Some example data types that are commonly used in FRC programming are:
 - String: Holds a sequence of characters.
   Denoted by double quotes (").
   Example: “Hello World”
-- char: Holds a single character.
-  Denoted by single quotes (').
-  Example: 'A'
 
-The name of your variable can be almost anything you want, but it should be easy to read and make sense to others who may be reading your code.
-One major exception is spaces, which are forbidden in variable names.
-Instead, you should write variables in what's known as camel case (`frontLeftDrive`).
-Upper snake case (`FRONT_LEFT_DRIVE`) should be used instead for constants, which we will learn about later in the course.
-Variable names can have numbers at any point except for the first character.
-(`motor2` is a valid name, `2motor` is not).
+<Aside type="note">
+    When creating a String, make sure the S is capitalized! `string robotName =
+    "Plunk"` will throw an error but `String robotName = "Plunk"` will not.
+</Aside>
+
+### Name
+
+In Java, variable names may only be letters, numbers and underscores `_`, and variable names cannot start with numbers.
+The name of the variable can be whatever you want, however, we recommend making them descriptive and easy to read.
+This will make it much easier for you to understand your own code and for others to help you.
+
+One common variable naming style is camel case, where each word is capitalized except the first.
+For example, `frontLeftDrive`, `currentTemperature`, and `targetPosition` are all camel case.
+Another common variable naming style is upper snake case, where each word is capitalized and an underscore is used in between each word.
+For example: `BACK_LEFT_DRIVE`, and `GEAR_RATIO` are in upper snake case.
 
 <Aside type="note">
 Java is a case-sensitive programming language!
@@ -75,14 +71,16 @@ Even though it’s spelled the same, if your variable name is MotorID then you t
 
 </Aside>
 
+### Semi-colons
+
 In Java, semi-colons `;` are similar to a period in a sentence.
 It is what tells the compiler when a statement ends.
-Semi-colons are used commonly in programming and aren’t only for creating variables.
-We will see more examples of this later in the course.
+This makes having a semi-colon at the end of your code important.
+In most cases, not having a semi-colon will cause an error.
 
-In FRC, variables can be used to hold information about the robot and its different mechanisms.
-The example below shows 3 variables that were used for a climber mechanism, `CLIMBER_ID` is an integer that holds the motor controller ID number which is 51.
-`UP_POSITION` is a double that holds the value -33.5 and `DOWN_POSITION` is a double that holds the value 0.
+### Example
+
+Taking what we learned, the following are four variables that each use a different data type.
 
 ```java #variables
 
@@ -105,8 +103,9 @@ A print statement in Java looks like:
 
 ```
 
-What the print statement does is take information inside the parentheses, in the previous example, it’s “hello!”, and prints it out to the terminal screen.
-When using a print statement, the text that we want to print out goes inside the parentheses and is in quotes.
+The print statement takes information inside the parentheses, in the previous example, it’s “hello!”, and prints it out to the terminal screen.
+When using a print statement, you have to surround a string with quotes, to indicate that you want to work with that text literally.
+A print statement without the quotes will cause an error because the compiler will look for a variable by the name instead of printing.
 However, if we are printing out the value of a variable, then we do not need quotes, as shown below.
 
 ```java #printVariable
@@ -117,6 +116,9 @@ However, if we are printing out the value of a variable, then we do not need quo
 
 When programming, we use comments to write notes that explain what the code does.
 This helps make the code more readable for others because if they are unsure of what your code does, they can read your comments.
+Writing comments can also help you!
+By leaving comments that explain what code does, it can be helpful when trying to understand what your code does and it can be helpful for debugging.
+
 Comments are ignored by the compiler, which also means that you can use comments to prevent code from running.
 In Java, there are two types of comments: single-line comments and multi-line comments.
 
@@ -148,6 +150,24 @@ For example, this is a comment with two lines of text.
 
 ```
 
+### Writing Comments
+
+It's best to use comments to explain what the code is trying to do with words, rather then just restating the code.
+For example, this is a useful comment because it explains what the purpose is and how it accomplishes the task.
+
+```java #goodComment
+
+```
+
+This is not a useful comment because it doesn't tell the reader what the purpose of the code is.
+It just restates the code.
+
+```java #badComment
+
+```
+
+There's no need to use comments for every line of code, but if something might be confusing to someone else later (or even yourself), leave a comment!
+
 ## Java Fundamentals Exercise
 
 <Aside type="exercise">WIP</Aside>