Skip to content

Review of fundamentals. Some grammar, some semantic. #305

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
schveiguy wants to merge 3 commits into
base: main
Choose a base branch
from
+45 −44
Open

Review of fundamentals. Some grammar, some semantic. #305

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d42b25f
Review of fundamentals. Some grammar, some semantic.
schveiguy Sep 18, 2026
7fa5e36
Merge branch 'main' into stage0-fundamentals-review
zachwaffle4 Sep 19, 2026
252e0e6
Apply batched suggestions from code review
schveiguy Sep 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 45 additions & 44 deletions src/content/docs/learning-course/stage0/java-fundamentals.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,17 @@ codeRegionSources:

Syntax is the basic set of rules that all programs in a language must follow.
It's similar to writing.
In writing, the first word in a sentence has to start with a uppercase letter or all sentence need in a period.
In writing, the first word in a sentence must start with an uppercase letter and all sentences should end with a period.
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.
A variable might hold the temperature, the speed of the motor, or any other information the program might need.

To make a variable, there are 5 parts:
To declare a variable, there are 5 parts:

1. Data type
2. Name of the variable
Expand All @@ -36,46 +36,46 @@ This makes your programs more reliable and helps prevent some common errors beca

Some example data types that are commonly used in FRC programming are:

- int: Integer numbers that are positive or negative.
int only allows numbers without decimals.
Example: 12
- double: Numbers that are positive or negative.
Unlike int, double allows decimals.
Example: 34.1
- boolean: Either `true` or `false`.
- String: Holds a sequence of characters.
- `int`: Integer numbers that are positive or negative.
`int` only allows numbers without decimals.
Example: `12`
- `double`: Real numbers that are positive or negative.
Unlike `int`, `double` allows decimal numbers.
Example: `34.1`
- `boolean`: Either `true` or `false`.
- `String`: Holds a sequence of characters.
Denoted by double quotes (").
Example: “Hello World”
Example: `“Hello World”`

<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.
"Plunk";` will throw an error but `String robotName = "Plunk";` will not.
</Aside>

### Name

In Java, variable names may only consist of letters, numbers, and underscores (`_`), but variable names cannot start with a number.
The name of the variable can be whatever you want, however, we recommend making them descriptive and easy to read.
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.
Another common variable naming style is upper snake case, where each word is capitalized and an underscore is used between each word.
For example: `BACK_LEFT_DRIVE`, and `GEAR_RATIO` are in upper snake case.

When programming a robot, camel case is commonly used for creating variables.
Upper snake case is used for constants which are variables that are defined once and are not changed.
Upper snake case is used for constants, which are variables that never change once they're defined.

<Aside type="note">
Java is a case-sensitive programming language!
This means that uppercase and lowercase letters are treated as being two different things.
For example: MotorID is different from motorID.
Even though it’s spelled the same, if your variable name is MotorID then you try to reference it again but spell it as motorID, Java will see the two as different, and your code will get an error.
For example: `MotorID` is different from `motorID`.
Even though it’s spelled the same, if your variable name is `MotorID` and you try to reference it as `motorID`, Java will see the two as different, and the compiler will throw an error.

</Aside>

Creating variable names can be fun, but the names should be
As mentioned, we recommend making them descriptive and easy to read
Creating variable names can be fun, but the names should be descriptive and easy to read.

Using an intake motor as an example, here are some bad and good variable names:

Expand All @@ -90,42 +90,42 @@ Using an intake motor as an example, here are some bad and good variable names:
<tr>
<tr>
<td>
`F` Avoid short or one letter variable names. It's not
`f` Avoid short or one letter variable names. It's not
descriptive and doesn't make it clear what the variable is
for.{' '}

@schveiguy schveiguy Sep 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was unsure what these {' '} are for but I didn't see any effect in the rendered table.

for.
</td>
<td>
`FrontLeftMotor` Clearly describes what the variable name is
`frontLeftMotor` Clearly describes what the variable name is
for and it's easy to read.
</td>
</tr>
<td>
`Bingo` Avoid using random words. It makes it hard to know what
the variable is for.{' '}
`bingo` Avoid using random words. It makes it hard to know what
the variable is for.
</td>
<td>
`BackLeftMotor` The variable name is easy to read and it's
`backLeftMotor` The variable name is easy to read and it's
descriptive.
</td>
</tr>
<tr>
<td>
`Motor` Robots have many motors. It's not clear what the motor
`motor` Robots have many motors. It's not clear what the motor
is used for.
</td>
<td>
`IntakeMotor` Adding a mechanism name makes it clear that the
`intakeMotor` Adding a mechanism name makes it clear that the
motor belongs to the intake.
</td>
</tr>
<tr>
<td>
`IntakeMotorForTheTopIntakeRoller` This is too descriptive and
`intakeMotorForTheTopIntakeRoller` This is too descriptive and
the name is too long, which makes it hard to read.
</td>
<td>
`IntakeTopMotor` The variable name is shorter but it's easy to
know what the variable is for.{' '}
`intakeTopMotor` The variable name is shorter but it's easy to
know what the variable is for.
</td>
</tr>
</tbody>
Expand All @@ -135,6 +135,8 @@ Using an intake motor as an example, here are some bad and good variable names:

In Java, semi-colons `;` are similar to a period in a sentence.
It is what tells the compiler when a statement ends.
Java does not have what we call "significant whitespace".
That is, whitespace such as new lines, spaces, and indentation do not affect how your code is executed.

@schveiguy schveiguy Sep 18, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought this might add some clarification of why semicolons are necessary, but could also leave it out.

@EdanThomton EdanThomton Sep 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is slightly wrong; whitespace does affect code, but all whitespace is essentially treated as a single space (intmyVariable won't compile, but int myVariable will)

@EdanThomton EdanThomton Sep 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A good rewording might be:

That is, all whitespace (such as new lines, spaces, and indentation) are treated as a single space, and adding more does not affect how your code is executed.

@schveiguy schveiguy Sep 19, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "treated as a single space" is also not quite right. All whitespace is treated as whitespace, and is not significant except for the fact that it separates tokens. But this probably too much to dump on a beginner.

I wanted to elaborate on why semicolons are needed, struggling to find a good way to say this without the context of language specification.

Perhaps:

That is, all whitespace (such as new lines, spaces, and indentation) are treated identically, and adding more does not affect how your code is executed.

Like I said, maybe not critically important to include in the beginner class, if we are struggling to say the right thing, maybe just best to take it out (or I can move this to a separate PR).

@schveiguy schveiguy Sep 19, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just as an aside, I get a lot of complaints from students is about forgotten semi colons. They don't like having to do it, and syntax errors are often times more cryptic than semantic errors (because your code is often treated as something completely different than what you intended).

It just seems to a student unnecessary to require these things. Especially ones that might have experience with a language without them.

Forgotten braces are another one, especially when they don't indent properly. Maybe hygienic formatting comes in a later lesson, and I haven't read it yet. Or maybe it should be added as a new section.

In most cases, not having a semi-colon at the end of a line will cause an error.

### Example
Expand Down Expand Up @@ -162,7 +164,8 @@ A print statement in Java looks like:

```

The print statement uses information given inside the parentheses, in the previous example, it’s the String “hello!”, and prints it out to the terminal screen.
The print statement uses the information given inside the parentheses.
In the previous example, the String `“hello!”` is printed out to the terminal screen.
When using a print statement to output text, you have to surround the text with quotes, to indicate that you want to work with that text literally.
A print statement without the quotes will instead interpret the text as a variable name and attempt to print the data stored by that variable.
This may cause an error if you intended to print out the text literally since the text is likely not an existing variable.
Expand All @@ -183,11 +186,11 @@ Let's look at an example:

`speed` is set equal to 1, this will print out `Left Motor Speed 1`.
Notice the space between `Speed` and the `"`.
This is done to make the print out easy to read.
This is done to make the text easy to read.
`System.out.println("Left Motor Speed" + speed);` would print out `Left Motor Speed1` which isn't easy to read.

This can also be done using many variables.
Using an empty string, `" "`, a space can be added in between variables in a print statement.
A space can be added between variables using a string literal with the desired spacing.
Let's look at another example:

```java #stringConcatenation2
Expand All @@ -199,24 +202,23 @@ Java recognizes that one of the items being added is a string, and converts the

## Comments

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!
Leaving comments that explain what code does can be helpful when trying to understand what your code does and when debugging.
When programming, we use comments to document or explain what the code does.
This helps others understand the code's intent.
Writing comments can also help you to remember why you wrote the documented code!

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.

### Single-line Comments

Single line comments begin with `//` and mark the rest of the line as being a comment.
For example, the code below leaves the note of "This prints out Hello World." preceding the print statement
For example, the code below has a comment explaining what it does.

```java #singleLineComment

```

You will also see comments placed at the end of a line like the following
You might also see comments placed at the end of a line

```java #inlineComment

Expand All @@ -227,9 +229,8 @@ Whether you put your comments preceding or alongside code is up to you and what

### Multi-line Comments

Multi-line Comments start with `/*` and end with `*/` The text or code that is in between the two will turn into comments.
Multi-line Comments start with `/*` and end with `*/` The text or code that is in between the two is a comment.
Multi-line Comments are commonly used when you have many lines of text or need to turn a large amount of code into a comment.
For example, this is a comment with two lines of text.

@EdanThomton EdanThomton Sep 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it might be better to keep this line for consistency with other examples (see the one right below it)

@schveiguy schveiguy Sep 19, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe just "for example"?

I just found the statements repetitive.

"when you have many lines of text" ... "with two lines of text" ... "This is another line"

@schveiguy schveiguy Sep 19, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It also might be better to show a non trivial reason to add a multiline comment.


```java #multiLineComment

Expand All @@ -238,7 +239,7 @@ 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.
For example, this is a useful comment because it explains the code's purpose and how it accomplishes the task.

```java #goodComment

Expand All @@ -251,7 +252,7 @@ It just restates the code.

```

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!
There's no need to use comments for every line of code, but if something might be confusing or ambiguous to someone else (or even yourself), leave a comment!

## Java Fundamentals Exercise

Expand Down
Loading