SimpleReport Style Guide

This style guide is very much a WIP! Feel free to edit!

Java

We use the Google Java Style Guide as our baseline.

Our gradle spotlessApply command (run automatically when committing changes) will format some things based on this style guide, like formatting and spacing. However, the linter isn't strongly opinionated, so it won't catch everything.

Exceptions

Avoid throwing a generic Exception in the method signature, preferring to throw the explicit Exception type.

No:

private String getUserStatus(UUID id) throws Exception {}

Yes:

private String getUserStatus(UUID id) throws IllegalStateException, BadRequestException {}

Variable Names

SimpleReport follows the Java and Google style guide recommendations for variable names. In particular, we discourage prepending an underscore to local fields, so organizationService is used instead of _organizationService. See this PR discussion for more details: https://github.com/CDCgov/prime-simplereport/pull/4722#discussion_r1047852222

Frontend

Graphql Queries

All graphql queries used in a container component (a component that is the root of a view, e.g., Test Results View) should be placed in a operations.graphql file that lives in the relevant subdirectory. For example, for the Test Results View the file that lives in the testResults folder.

Whenever you change the location/contents of a query file, run the command yarn codegen. This will generate the necessary hooks that will allow you to call the query on the front end. For example, to fetch data using the query GetResultsCountByFacility you need to use the hook useGetResultsCountByFacilityQuery which will get automatically generated by the codegen command.

To see this example in action, check the file TestResultsList.tsx in the repo.

Linters

This project uses eslint, prettier, and stylelint as frontend linters, and spotless and google-java-format for the backend. GitHub Actions is configured to run these linters on every pull request, so you must resolve all mismatches/errors before merging. There are a few ways to manage this:

1. Run yarn lint:write in the frontend/ dir, and ./gradlew spotlessApply in the backend/ dir, before every commit
2. Enable the optional pre-commit hook by running yarn lefthook install in the root dir (install lefthook if you haven't already done so during setup by running yarn install)
3. Add extensions to your code editor that runs the linters for you on save, e.g., prettier-vscode, vscode-eslint, vscode-spotless-gradle

You can also run the pre-commit hooks in docker using yarn lefthook run in-docker.