Review of fundamentals. Some grammar, some semantic. by schveiguy · Pull Request #305 · frcsoftware/frcsoftware.org

schveiguy · 2026-09-18T04:26:37Z

Description

What changed?

Rewording/grammar changes.

Why? (the code + comments should speak for itself on the "how")

Proofreading

Meta

Merge checklist:

Pull Request title is short, imperative summary of proposed changes
The description documents the what and why, including events that led to this PR
Pull Request has been linted and formatted and follows the styleguide

schveiguy · 2026-09-18T04:27:14Z

-                    `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.{' '}


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

schveiguy · 2026-09-18T04:27:55Z

 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.


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

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)

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.

EdanThomton

A few grammar mistakes, consistency changes, and wording changes + a few comments on stuff

EdanThomton · 2026-09-18T18:29:33Z


 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 or it might hold the speed of the motor.


Suggested change

A variable might hold the temperature or it might hold the speed of the motor.

A variable might hold the temperature, the speed of the motor, or any other information the program might need.

Not needed, but this reads better IMO

EdanThomton · 2026-09-18T18:29:59Z

+  `int` only allows numbers without decimals.
+  Example: `12`
+- `double`: Numbers that are positive or negative.
+  Unlike `int`, `double` allows decimals.


Suggested change

Unlike `int`, `double` allows decimals.

Unlike `int`, `double` allows decimal numbers.

EdanThomton · 2026-09-18T18:30:41Z

+- `int`: Integer numbers that are positive or negative.
+  `int` only allows numbers without decimals.
+  Example: `12`
+- `double`: Numbers that are positive or negative.


Suggested change

- `double`: Numbers that are positive or negative.

- `double`: Real numbers that are positive or negative.

EdanThomton · 2026-09-18T18:34:32Z


 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 are defined once and are not changed.


Suggested change

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.

reads better IMO

EdanThomton · 2026-09-18T18:35:43Z

-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` then you try to reference it but spell it as `motorID`, Java will see the two as different, and the compiler will throw an error.


Suggested change

Even though it’s spelled the same, if your variable name is `MotorID` then you try to reference it but spell it as `motorID`, Java will see the two as different, and the compiler will throw an error.

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.

EdanThomton · 2026-09-18T18:42:12Z

-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 make sense of the code's intent.


Suggested change

This helps others make sense of the code's intent.

This helps others understand the code's intent.

EdanThomton · 2026-09-18T18:42:56Z


 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 is documented as to what it achieves.


Suggested change

For example, the code below is documented as to what it achieves.

For example, the code below has a comment explaining what it does.

EdanThomton · 2026-09-18T18:43:48Z

 ```

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


Suggested change

You might also see documenting comments placed at the end of a line

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

I don't think "documenting" is needed here, as it's generally implied that all comments should be documenting something

EdanThomton · 2026-09-18T18:44:19Z

 ### 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 will be treated as comments.


Suggested change

Multi-line Comments start with `/*` and end with `*/` The text or code that is in between the two will be treated as comments.

Multi-line Comments start with `/*` and end with `*/` The text or code that is in between the two is a comment.

EdanThomton · 2026-09-18T18:45:12Z

-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 will be treated as comments.
 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.


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

github-actions · 2026-09-19T04:58:02Z

🌐 Preview URL: https://pr-305-frcsoftware.frcsoftware.workers.dev

Changed pages

Review of fundamentals. Some grammar, some semantic.

d42b25f

github-actions Bot added Curriculum material Curriculum materials, lessons for students, etc stage0 labels Sep 18, 2026

schveiguy commented Sep 18, 2026

View reviewed changes

samfreund approved these changes Sep 18, 2026

View reviewed changes

EdanThomton suggested changes Sep 18, 2026

View reviewed changes

Merge branch 'main' into stage0-fundamentals-review

7fa5e36

	A variable might hold the temperature or it might hold the speed of the motor.
	A variable might hold the temperature, the speed of the motor, or any other information the program might need.

	Unlike `int`, `double` allows decimals.
	Unlike `int`, `double` allows decimal numbers.

	- `double`: Numbers that are positive or negative.
	- `double`: Real numbers that are positive or negative.

	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.

	Even though it’s spelled the same, if your variable name is `MotorID` then you try to reference it but spell it as `motorID`, Java will see the two as different, and the compiler will throw an error.
	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.

	This helps others make sense of the code's intent.
	This helps others understand the code's intent.

	For example, the code below is documented as to what it achieves.
	For example, the code below has a comment explaining what it does.

	You might also see documenting comments placed at the end of a line
	You might also see comments placed at the end of a line

	Multi-line Comments start with `/` and end with `/` The text or code that is in between the two will be treated as comments.
	Multi-line Comments start with `/` and end with `/` The text or code that is in between the two is a comment.

Conversation

schveiguy commented Sep 18, 2026

Description

Meta

Uh oh!

schveiguy Sep 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EdanThomton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Sep 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

schveiguy Sep 18, 2026 •

edited

Loading