This library manages the formatter and linter CLI for Java on numbers. It allows students to format their code according to Google's Java style guide.
The purpose of this library is to help students understand the importance of code style. It shows them how to properly format Java code, and teaches them to lint their code to identify a variety of infelicities.
Installing the latest version of java-code-quality simply requires downloading the latest release and running the install.sh file with bash. Any previous versions are automatically removed by the installer.
Note that the format checker script depends on a Python3 and pip installation. The installation script will attempt to globally install a package with pip3. If this script is not necessary, any errors pertaining to this step may be safely ignored.
The latest version may be installed with the following steps:
-
Download the
zipfile from the latest release. -
Transfer the
zipfile to the server where it will be installed. -
In a terminal, unzip the file using the following command:
unzip java-code-quality-x.y.z.zip- Enter the new
java-code-qualitydirectory:
cd java-code-quality- Make the
install.shfile executable, and then run it as the superuser:
sudo bash install.sh- You may now safely delete the
java-code-qualitydirectory and thezipfile. The latest version has been installed.
Eastern University defaults to Google's style guide for Java with the exception of using four-space indentation.
Google provides a Java program that automatically formats a given Java file to their standards. (When run with the --aosp flag, it uses four-space indentation).
Since this script requires a number of flags to account for, among other things, modern Java versions and the indentation exception, it is encased in a custom format command added to numbers. Students can thus format their code with the following command:
format [file]
Linting of Java files is done through Checkstyle. From their website:
Checkstyle is a development tool to help programmers write Java code that adheres to a coding standard. It automates the process of checking Java code to spare humans of this boring (but important) task. This makes it ideal for projects that want to enforce a coding standard.
Checkstyle supports Google's style guide through the use of a custom configuration file.
Similar to Google's formatter, Checkstyle is packaged in a jar file that can be manually executed on student's code. Again, to avoid having students memorize a series of flags to run Checkstyle, it is packaged in the custom lint command added to numbers. Students can thus lint their code with the following command:
lint [file]
The following versions of the formatter and linter are currently in use:
- google-java-format: 1.15.0
- Checkstyle: 10.5.0
- Checkstyle Google configuration: Last updated 2022-12-30
To update these files, simply download them from the links below and overwrite the current versions in the data directory. Make sure to name them appropriately.
Download from the GitHub repo releases page. Make sure to get the "all-deps" version.
Remove the version number from the file name to allow the format command to identify it. Name it google-java-format-all-deps.jar.
Download from the GitHub repo releases page.
Remove the version number from the file name to allow the lint command to identify it. Name it checkstyle.jar.
The google_checks.xml file was originally downloaded from the Checkstyle GitHub repository, as linked from the Google support page. At the time of download, it was last updated 2022-08-15.
However, this file has since underwent significant modification to reflect the style conventions used at Eastern University. Therefore, it is inappropriate to simply download an updated version and replace the current copy.
Instead, see the style guide changes document for detailed information about what elements of the xml were changed and why. In the event that updates are pushed to the source file in Checkstyle's repository, those changes should be individually applied to the local google_checks.xml file with appropriate documentation in the style guide changes document.
After updating one or more of the above dependencies (or anything else in this library), complete the following steps in order:
-
Update the version number according to semantic versioning. Note that dependency updates are considered minor changes.
-
Commit all changes to GitHub.
-
Next, run the
package.shscript to create a zip package with the following commands:
Note: You must run the script from within its parent directory.
cd java-code-quality/
bash package.sh-
Upload the created zip file to GitHub as a new release.
-
Install the new package on numbers.
This library also comes with another utility, format_checker.py. This is a Python script that can validate the formatting of student code.
It works by making a temporary copy of the student's code and formatting the copy. Then, the Levenshtein distance between the unformatted and formatted code is calculated. Finally, a grade between 0 and 1 is output based on the number of changes the formatter made to the code, as indicated by the Levenshtein distance.
This script accepts any number of files or directories as parameters. Directories are indexed and all .java files are tested. When testing multiple files, the total Levenshtein distance for all files is computed, and the grade is assigned based on this number as it would be for a single file.
The script is automatically installed in the java-code-quality directory by the installer. Note that it requires the python-Levenshtein package, which is automatically installed globally using pip3.
To call the script on Foobar.java, use the following command:
python3 /opt/java-code-quality/format-checker.py Foobar.javaCreated by: Simon Kwilinski
Last updated: 2022-12-30