Code Standards

From Team 449 Wiki

This page describes how finalized, polished robot code should be formatted, commented, etc.

Commenting

Every field, method, class, or interfaces should have a javadoc comment describing what it is or does. For methods, all methods other than simple getters and setters should have a description, and all methods should have the @param and @return tags filled out if possible. For constructors, if a parameter is optional to put in the config file or can be null and, if so, will default to a specific value, add to the end of the parameter's description "Defaults to [value]." The description for a field, the constructor parameter that sets it, and the @param or @return of a getter or setter for a field should all be about the same, with the main difference being that only setters and constructor parameters include the "Defaults to." In line comments should be included as much as makes sense. If you're unsure whether to put an in-line comment, put it.

Annotations

All non-primitive parameters, fields, and methods should be annotated with either @NotNull or @Nullable, from the org.jetbrains.annotations package. In addition, @Override should be used whenever possible, and if IntelliJ recommends it, put in @Contract annotations.

Formatting

We use IntelliJ's google-java-format plugin instead of the builtin autoformatter. If you're using VS Code, there are extensions using Google's Java formatting style too. Do note that if you use the IntelliJ plugin, you'll have to enable it separately for every project you want to use it for. To format in IntelliJ, use Ctrl+Alt+L (or Ctrl+Alt+Shift+L to customize how you want to do it).

Templates

Under the base-level directory of 449-central-repo, there's a directory called "templates." This contains templates for most of the different file types you'll use to write robot code. You should copy paste them in and change as little of the comments and structure of the templates as possible. This allows for consistency across multiple different files. One template, "GenericStateChangeCommand," should be used whenever writing a command that makes an instantaneous change and then exits (e.g. change the speed of a motor or extend a piston). If isFinished should always return true, odds are it's a state change command.