Frequently Asked Questions

Problem/Tip	Try This
Installing Git - (if your lab computer does not have git installed)	Run this on the terminal: `winget install --id Git.Git -e --source winget` Note: You will need to restart VS code if it was running before you installed git (or restart the terminal) so windows can find the installed version of git.
Java tests do not appear, or the main class does not load or run.	Run Clean Java Server Workspace: 1. Press `CTRL+SHIFT+P`. 2. Enter `clean java server workspace`. 3. Select Reload & Delete. 4. Repeat the process if necessary. 5. If you are using Codespaces, remove the temporary files by running `sudo rm -rf /tmp/*`.
Java FX codespaces loading in recovery mode?	See how to disable the sound drivers from loading here.
Java FX won’t run on codespaces: `Error: JavaFX runtime components are missing, and are required to run this application`	Open up and look at the file: `.vscode/launch.json` It’s likely you have changed or created a different app that is missing the “linux” section that is needed to find the java fx libraries. Copy that section over to your current configuration so it can find the libraries again. You can usually tell if you see a “projectname” section that is not set to an empty string project name. You can safely delete this launch configuration and use the original one I set up for you instead. “linux”: { “vmArgs”: “–module-path …
Codespaces shows error running the UI port window (x -Failed To Connect To Server)	Try “SHIFT-REFRESH” in your browser window for the VNC UI port. This will delete all cached data in the browser window and seems to fix this problem.
I don’t know how to use Git/GitHub	There are video tutorials here and we also have a set of tutorials hosted at the NCHS website here
I am confused about codespaces	GitHub codespaces directions are here. NCHS specific directions and help are in this doc below here.
Running Java UI from VS Code results in X11 display issue	This results from clicking to open the project directly to VS code with the “Open in VS code” from the classroom. (It’s trying to run codespaces remotely but this doesn’t work for Swing). Instead clone the repository from VS Code (create a new window and select to clone a repository and use the link for your github repository from GitHub to clone it). This will then run as expected in your local VS code. Alternatively run remotely and follow directions below for running in CodeSpaces.
GitHub complains you don’t have user.name or user.email	`git config --global user.name "Your name"` `git config --global user.email <id>@apps.nsd.org`
If you have an ssl issue in vscode saving your work	`git config --global http.sslVerify false`
When trying to clone a repository to a local machine: “SSL certificate problem: self-signed certificate in certificate chain”	If you are on Windows: enter this on the terminal to configure ssl correctly `git config --global http.sslbackend schannel` On linux/codespaces: `git config --global http.sslbackend openssl`
“Sync” fails / conflict (when trying to submit)	Enter this into the terminal and sync again: `git config set pull.rebase true`
“Commit” looks it’s taking forever	Make sure you don’t have the “COMMIT_MSG” file up and waiting for you to edit and close. Just close it and put your commit message in above the commit button.
Other random codespace error or message of something weird (aka rebuild codespace)	Warning this will lose any changes you haven’t pushed to your github repo Enter Ctrl-Shift-P for the command palette, type “Reb…” to get “Codespaces: Rebuild Container”, select “Full Rebuild”.
Trying to run java main isn’t working (e.g. main is not found or perhaps the java run/play button is missing)	Check you have enabled the Microsoft java extension pack and not the oracle one. This is correct: This doesn’t fully support VS code use:
How can I view the changes I’ve made as a summary of my daily work in powershell? This will show your daily classwork output for teacher review	(git log --date=format-local:'%Y-%m-%d %H:%M' --pretty=format:'%n@@%h%x09%ad%x09%an%x09%s' --shortstat \\| Out-String) -split '@@' \\| ? {$_.Trim()} \\| % { i=if(_ -match '(\d+) insert'){$matches[1]}else{0}; d=if(_ -match '(\d+) delet'){$matches[1]}else{0}; "+$i`t-d`t"+(_.Trim() -split '\r?\n')[0] }

Markdown

Markdown syntax allows rich formatting in documents using any plain text editor.

Basic Markdown Guide

Here is a basic markdown guide: markdownguide.org

Integrating with Google Docs

You may upload and download markdown documents to Google Docs. To edit a markdown document in Google Docs, upload the document and then edit in Google Docs.

Note you must use the Google Drive “upload” feature or from Google Docs you can select File → Open to directly open the markdown document (this is the easiest way).

Whenever you want to save the current version of the document choose File → Download → Markdown.

Warning: If you include images in your Google documents these will be encoded in the markdown content. It’s often better to just edit the markdown document directly instead of using Google Docs if you make heavy use of images that you may modify and replace so you can reference these with markdown links to image files.
Signing up for GitHub

It’s recommended that you create a “school” github account. To do this you can use your google SSO (single sign on) and you should create your account username with the following credentials using “firstname-lastname” for your username. Do not enable 2 factor authentication as this will cause you to need to use your phone or other device when you sign in.

GitHub Education Accounts

If you run out of time in GitHub codespaces apply for a free GitHub education account. Here’s how to do that:

You can request an education account here which will take you to your settings for your github account to start the application process.

Do not put in any billing information. Make sure to select that you are a student. You may need to turn on two factor authentication and verify your email address. Make sure to set two factor to use your email address so you can still reset and access your account in school without your phone. Do not set two-factor to your phone number as it disrupts class to have to use your phone for two factor authentication.

You need proof that you are a student so you’ll need to edit and print the following document for you to use during the signup process (I’ll need to sign it for you too): Google Doc Link.
Remove Redundant Launch Configurations

Every time you hit the “play” button on a java file VS code creates a new project name specific to the computer you are on. You get a message that the project name is not a valid project if you try and run the configuration from Run and Debug too:

Edit your launch.json and simply remove the projectName setting; it’s not necessary.

Coding Style Guidelines

As we dive into Java development, we will be adhering to the Google Java Style Guide. We could have picked guidelines from other large companies to follow but this one was the most popular in the search results right now. This guide isn’t just about making code “look pretty”; it is an industry standard for creating professional, maintainable, and readable software. By following these rules, you ensure that your code is “in Style,” covering everything from naming conventions to how we handle braces and imports.

Why Use a Coding Guide?

If you’re wondering why we don’t just let everyone code their own way, here are five key reasons:
- Readability: Code is read much more often than it is written. A consistent style allows team members (and your instructors) to understand your logic at a glance without being distracted by unusual formatting.
- Maintainability: Standardized code is easier to debug and update. When everyone follows the same rules, “ownership” of the code shifts from the individual to the team.
- Reduced Cognitive Load: You shouldn’t have to spend brainpower deciding where to put a curly brace. A style guide makes these decisions for you, letting you focus entirely on solving the actual problem.
- Error Prevention: Rules like always using braces for if and else blocks help prevent common logic bugs that occur when code is modified later.
- Professionalism: Learning to follow a style guide prepares you for the real world. Almost every major tech company enforces a specific style to ensure high-quality software across thousands of developers.
Tooling: Automated Formatting

To make following these rules effortless, we will use an automated formatter. This ensures your code is corrected every time you save.

Install the Extension
1. Open VS Code.
2. Go to the Extensions view (click the square icon on the left or press Ctrl+Shift+X)
3. Search for and install: josevseb.google-java-format-for-vs-code.
Configure Settings

To ensure the extension works correctly, update your workspace settings. Create or open the .vscode/settings.json file in your project folder and add the following configuration to the existing configuration there.
```
{
 "java.format.settings.url": "https://raw.githubusercontent.com/google/styleguide/gh-pages/eclipse-java-google-style.xml",
 "java.format.settings.profile": "GoogleStyle",
 "[java]": {
 "editor.defaultFormatter": "josevseb.google-java-format-for-vs-code",
 "editor.formatOnSave": true,
 "editor.insertSpaces": true,
 "editor.tabSize": 2
 }
}
```
Applying Style to an Existing Project

If you already have a project full of code, you will need to open every file manually to fix the formatting. Open each file and save the file to trigger an update in formatting.

Commit the Changes

Once the formatter has touched your files, your Source Control tab will show several modified files. To keep your history clean, commit these as a single “style update”:
1. Go to the Source Control tab (the branch icon on the left).
2. Stage all changes by clicking the + (plus) icon next to “Changes”.
3. In the message box, type: style: apply google-java-format to project
4. Click Commit.
By committing formatting changes separately from logic changes, you make it much easier for others to review your “real” code work later!

Running Java Apps Standalone (jar files)

Create your JAR
1. Go to visual studio
2. Press CTRL+SHIFT+P
3. Type “export jar”
4. Select your “Main” class (whatever your main is in)
Your “jar” file is created in your root folder

You shouldn’t need add additional javafx libraries to your jar files for other students to be able to run it because we have the Zulu FX SDK installed on school computers to support all the FX libraries.

Test your JAR

If you are using codespaces

Download from codespaces to your local computer and run the jar from there.

If you are using visual studio

NOTE: To test you should copy your jar file to a different location (otherwise it still has access to your other files, which it won’t when you copy and share it).

Run a JAR file

Test out running it with these steps to run someone else’s “jar” file:
1. Go to the command prompt: (You can right click in explorer and select to Open in Terminal)
2. Type java -jar <filename.jar>
For example:
```
java -jar myfungame.jar
```
Common Gotchas

NOTE: You need to change image reading (or any other “file” access) to the following API instead:
```
BufferedImage img = ImageIO.read(getClass().getResourceAsStream("/path/img.png"));
```
You can’t use exists or other direct File access (except for things like save game files etc that you truly want as files on the destination computer).

How to Create and View Javadocs

Javadocs are required for most homework assignments. They are an industry standard practice for Java coding and often at most companies you will be required to have sufficient Javadoc commenting in place for the work you do to be accepted. So for this course we will make sure we get into the practice of always creating our javadocs for each project.

Commenting your Code for Javadoc

The first step you must take is to include javadoc comments in your code. A javadoc comment begins with “/**” and ends with “*/”. At a minimum your javadoc comments for methods should include a description of each method, the parameters (@params) and any return parameter (@return) described - typically with a single line comment. You may use html markup such as <a> or  tags in the example below, but is not required.

You must also have the following comment block at the top of each class you create. Do not leave any blank lines after this so this comment is connected to the class you are commenting.
```
/** Responsibility:
* - __What is this class responsible for?__ 
* 
*
* @doc.implNote
* <pre>
* IS-A:
* - __Superclass, or "Object" if none__
*
* HAS-A:
* - __Important fields or contained classes__
*
* DOES:
* - __Interfaces it implements / behaviors__
*
* Notes:
* - __Any design decisions, invariants, or assumptions__
* </pre>
*
* @doc.collaborators __Other classes it works with or depends on__
*
* @doc.testing __How was/is this class tested? (e.g. Manually, Junit etc)__
*/
```
See this guide for a beginners guide to the documentation on javadoc parameters and the full javadoc 23 specification.

You can use the following tasks.json file in your vscode project to run the javadoc command: tasks.json

VS Code Tools to Help

You may install VS Code tools to help with your documentation. The javadoc tool helps you out by putting javadoc comments (stubs) for your public methods - you’ll still need to fill in the details of the methods.

Building the Javadocs

Standard Java

Note: This will not work for Java FX projects (see section below)

To build javadocs you must run a command to export/create the javadoc html files from your comments. The best way to create your javadocs is just to run the javadoc command on the terminal/command line directly like this (Note; you must be in the parent directory of all of your java files)

For linux/codespaces:
```
javadoc -d docs $(find . -name "*.java")
```
For windows/VS Code:
```
javadoc -d docs (Get-ChildItem -Recurse -Filter *.java).FullName
```
This will likely generate a number of errors/warnings. You should go through these and fix as many as you can to make sure you’ve fully commented on your project.

Java FX

For Java FX we have set up a build task to create javadocs on most projects. You can run the task to build your javadocs with CTRL-SHIFT-B or CTRL-P + “Run Build Task” (this is only set up for our specific github classroom assignment). After running you should see a docs folder.

Downloading and Viewing the Javadocs

From VS Code/Codespaces: Install the following extension

After you install an HTML preview extension you can right click on the docs/index.html file and “Open Preview”. Note that in codespaces you will need to reload the window for it to work the first time.

For codespaces: You may also download the files from your codespace to your local computer. Right click on the “docs” folder and select to download that directory. You’ll get all the files downloaded locally (likely to your “Downloads” folder). You don’t need to do this if you are working in windows locally with VS code.

Once you have the files on your computer you can view the files locally. Find the location of your index.html file by right clicking on the file in the toolbar and selecting “Show in Explorer” (Or if you downloaded the files just find them directly). From there you can just double click the index.html file to open the javadoc content → confirm that all your expected comments show up including the class comments and public method comments.

PMD

https://pmd.github.io/

About PMD

PMD is an extensible multilanguage static code analyzer. It finds common programming flaws like unused variables, empty catch blocks, unnecessary object creation, and so forth. It’s mainly concerned with Java and Apex, but supports 16 other languages. It comes with 400+ built-in rules. It can be extended with custom rules. It uses JavaCC and Antlr to parse source files into abstract syntax trees (AST) and runs rules against them to find violations. Rules can be written in Java or using a XPath query.

Currently, PMD supports Java, JavaScript, Salesforce.com Apex and Visualforce, Kotlin, Swift, Modelica, PL/SQL, Apache Velocity, JSP, WSDL, Maven POM, HTML, XML and XSL. Scala is supported, but there are currently no Scala rules available.

Additionally, it includes CPD, the copy-paste-detector. CPD finds duplicated code in Coco, C/C++, C#, CSS, Dart, Fortran, Gherkin, Go, Groovy, HTML, Java, JavaScript, JSP, Julia, Kotlin, Lua, Matlab, Modelica, Objective-C, Perl, PHP, PL/SQL, Python, Ruby, Rust, Salesforce.com Apex and Visualforce, Scala, Swift, T-SQL, Typescript, Apache Velocity, WSDL, XML and XSL.

Main PMD Issues

Following are the main metrics that I use to assess class design and modularity. I do look at other metrics as well but these are the main ones that would affect your grade the most.

Metric	Why it matters for your Rubric
`GodClass`	Critical. This is the #1 enemy of modularity. A “God Class” knows and does too much. If this number is anything above 0, you have a class that violates the Single Responsibility Principle. Fix this first.
`CyclomaticComplexity`	Stability. This measures how many paths exist through your code. High numbers = “spaghetti code” that is impossible to unit test effectively. This directly tanks your stability score.
`TooManyMethods`	Modularity. If a class has too many methods, it’s not modular—it’s bloated. This is often a symptom of failing to break a class down into smaller, focused helpers.
`DataClass`	Design. A Data Class is just a container for data with no real behavior (just getters/setters). In good OOD, objects should do things, not just hold things.

Rules Configuration

How to Run at School

Save the rules.xml file here to your project.

Download the PMD files for windows to your computer (the rules above are using PMD version 7.24.0 but later versions should work too). You must use the following powershell for this download and it saves your files to your Downloads folder.

 Invoke-WebRequest -Uri https://github.com/pmd/pmd/releases/download/pmd_releases%2F7.28.0/pmd-dist-7.28.0-bin.zip -OutFile  $env:USERPROFILE\Downloads\pmd.zip

 Expand-Archive -Path "$env:USERPROFILE\Downloads\pmd.zip" -DestinationPath "$env:USERPROFILE\Desktop"

 [Environment]::SetEnvironmentVariable("Path", "$([Environment]::GetEnvironmentVariable('Path', 'User'));$env:USERPROFILE\Desktop\pmd-bin-7.28.0\bin", "User")

Now to get this to load into your environment restart VS code.
To Run pmd on your project you just need to run the following (assuming your code is all in the src\main folder. The results will be visible in a new file “pmd_results.txt” (you may check this into your project if you like). You may also save this to run-pmd.ps1 and run this command from the terminal each time to check your work.

# Run from your project folder
pmd check -d .\src\main -R rules.xml -r pmd_results.txt 

Java FX - Installing on Another Computer

Download and install the Zulu FX Java FX SDK from here. Be sure to scroll down and select the Java FX SDK, not the default SDK. You can install the latest (v25) at this time.

For windows: use the “msi” file. Be sure to set the “JAVA_HOME” environment parameter during the install.

Java FX Download

Java FX - Missing Libraries

When trying to build you may find that VS code cannot locate the FX libraries. You’ll need to point your visual studio to where the FX libraries are located.

Add the following to your .vscode/launch.json (add a new line right after projectname):

"vmArgs": "--module-path \"${env:JAVA_HOME}\\lib\" --add-modules=javafx.controls,javafx.fxml --enable-native-access=javafx.graphics"

Or in your user settings (JSON):

"java.debug.settings.vmArgs": "--enable-native-access=javafx.graphics --sun-misc-unsafe-memory-access=allow --module-path \"${env:JAVA_HOME}\\lib\" --add-modules=javafx.controls,javafx.fxml"

Suppressing JavaFX Warnings

To suppress the following warnings:

WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::load has been called by com.sun.glass.utils.NativeLibLoader in module javafx.graphics (jrt:/javafx.graphics)
WARNING: Use --enable-native-access=javafx.graphics to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled

WARNING: A terminally deprecated method in sun.misc.Unsafe has been called
WARNING: sun.misc.Unsafe::allocateMemory has been called by com.sun.marlin.OffHeapArray (jrt:/javafx.graphics)
WARNING: Please consider reporting this to the maintainers of class com.sun.marlin.OffHeapArray
WARNING: sun.misc.Unsafe::allocateMemory will be removed in a future release

Add this line to your user settings.json (CTRL-SHIFT-P → User Settings (JSON)):

"java.debug.settings.vmArgs": "--enable-native-access=javafx.graphics --sun-misc-unsafe-memory-access=allow"

Or open User Settings (UI) and search for vmargs and add:

--enable-native-access=javafx.graphics --sun-misc-unsafe-memory-access=allow

Vmargs Photo

Codespace Usage

Note: GitHub as of 08/31/2026 no longer supports codespace billing to a group organization. You must obtain GitHub Education approval to receive any codespace usage credits for free.

Setting up Codespaces for HW

For most assignments you can work with your GitHub code in either VS code or codespaces. To work in codespaces you may have some additional setup (e.g. see the sections below for setting up to run a GUI for Java FX for instance).

If your assignment has automated testing set up for it you can find the steps here that will help you set up a separate environment and the dependencies you are going to need to run it either on codespaces or your own separate environment.

Java FX Codespace Issues (loaded in recovery mode)

If you are having codespace issues, I’ve found that the installation of the sound drivers for javafx seems to be causing problems. Open your .devcontainer/setup-javafx.sh file and change the apt-get install (around line 21) to the following to remove the sound drivers. Commit, Sync(Push) changes, and do a “Full Rebuild” on your container.
```
# disable sound install - issues with package names and won't use sound on codespace anyway
sudo apt-get install -y libgtk-3-0 libx11-6 libxtst6 libxrender1 libxi6 libgl1 >/dev/null
```
Running Java FX from Codespaces

It is possible to run Java FX from codespaces instead of VS Code locally on your machine. You should be able to start a new codespace from github.com/codespaces and provide it your github url for your project, or you can create the codespace directly from your github repository.

To do this follow these steps:

If this is not already in your .devcontainer, add the following directory to the root of your project: .devcontainer and add a new file devcontainer.json to this folder with the following:
```
{
    "name": "Java Swing Development",
    "image": "mcr.microsoft.com/devcontainers/java:17",
    "features": {
        "ghcr.io/devcontainers/features/desktop-lite:1": {
            "password": "vscode"
        }
    },
    "forwardPorts": [
        6080
    ],
    "portsAttributes": {
        "6080": {
            "label": "Desktop (Web)"
        }
    }
}
```
Restart your codespace - you can do this with the directions in the help table on how to “Rebuild codespace”.

After it restarts you should be able to go to the “ports” section and click the globe (open in browser).

This should open up a browser tab to connect to VNC.

Click connect and you should now be able to run your GUI application from codespaces and have it come up in there.
Classroom50

Your teacher will provide you with the link for your specific assignments (The only exception here is for the IDP nchs-idp assignment below. You should see the following screen (if you are not yet signed into GitHub).

Once you’ve accepted an assignment you will have your own private repository for this assignment.

IDP

For IDP you can use the following assignment for your classwork and assignments: https://classroom50.org/NCHS-CS/idp/assignments/nchs-idp/accept

Once you accept this assignment you can clone the repository to your computer.

You can now work on the jupyter notebooks locally using VS Code (and read the lesson content). See notes on running VS code from Anaconda here NCHS CS Help for FAQ

Updating your assignment

At times I will make updates to the website and you will want to incorporate these into your repository. To do this you’ll need to follow a few more steps.

First - you need to add the original IDP website as an upstream repository. Note - you only need to do this once.
```
git remote add upstream https://github.com/NCHS-CS/cse163-nchs
```
You can now fetch and merge upstream changes.
```
git fetch upstream
-git merge upstream/main --allow-unrelated-histories
```
Gotchas:
1. The very first time you use git you may get an error for git user.name (go to the FAQ table!)
2. The command line git defaults to the editor “vi” and you get are stuck..: It’s a text editor when you get the merge commit and it’s just looking for your description to be saved. Press “Esc” to make sure you are in editor mode. Enter the text :x and press enter (the vi command to save a file).
3. If you get merge conflicts you can throw away your changes and accept the upstream version with (especially for jupyter notebook conflicts that can be hard to merge):
```
# How do throw out your changes and get the "upstream" file to your repo.
git checkout --theirs <file_name>
git checkout --ours <file_name> # to keep our file
```
Tip: Subscribe to notification and changes to the main website so you can decide when to update your local repository. Go to the upstream repository and select to watch all notification in the UI:

Submitting your Assignment for Grading

In order for classroom50 to recognize your latest commit as the work that needs to be graded, you need to tag it.
```
# First: Create a tag, and make sure it's titled 'submit/final'.
git tag -f submit/final
# This only updated the tag's location on your local system.
# In order to move it to the servers, you need to push it!
git push origin submit/final --force
```
Gotchas:
1. If you don’t title the tag correctly, classroom50 will NOT grade it properly
2. Not forcing both commands will cause git to tell you that ‘submit/final’ already exists as a tag.
3. Make sure you place the –force command in the right place, so everything actually works correctly.