{"id":21363156,"url":"https://github.com/firstteam102/java-style-guide","last_synced_at":"2026-01-02T17:34:17.968Z","repository":{"id":223343997,"uuid":"760059309","full_name":"FIRSTTeam102/java-style-guide","owner":"FIRSTTeam102","description":"Team 102's (currently in-progress) style guide for WPILib Java","archived":false,"fork":false,"pushed_at":"2025-03-02T22:00:11.000Z","size":28,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-02T23:18:01.780Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FIRSTTeam102.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-19T17:52:35.000Z","updated_at":"2025-03-02T22:00:14.000Z","dependencies_parsed_at":"2024-03-21T01:32:18.265Z","dependency_job_id":"a38b8f1b-5009-430b-ae63-551303fd3c0b","html_url":"https://github.com/FIRSTTeam102/java-style-guide","commit_stats":null,"previous_names":["firstteam102/java-style-guide"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FIRSTTeam102%2Fjava-style-guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FIRSTTeam102%2Fjava-style-guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FIRSTTeam102%2Fjava-style-guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FIRSTTeam102%2Fjava-style-guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FIRSTTeam102","download_url":"https://codeload.github.com/FIRSTTeam102/java-style-guide/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243836025,"owners_count":20355616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-22T06:18:12.329Z","updated_at":"2026-01-02T17:34:17.942Z","avatar_url":"https://github.com/FIRSTTeam102.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Table of Contents\n\n- [Table of Contents](#table-of-contents)\n- [1 Introduction](#1-introduction)\n\t- [1.1 Terminology Notes](#11-terminology-notes)\n\t\t- [1.1.1 Rule Importance Terms](#111-rule-importance-terms)\n\t- [1.2 Guide Notes](#12-guide-notes)\n- [2 Source File Structure](#2-source-file-structure)\n\t- [2.1 Terminology](#21-terminology)\n\t- [2.2 Package Statement](#22-package-statement)\n\t- [2.3 Import Statements](#23-import-statements)\n\t- [2.4 Class Declaration](#24-class-declaration)\n\t\t- [2.4.1 Class Member Ordering](#241-class-member-ordering)\n\t\t\t- [2.4.1.1 Overloads: never split](#2411-overloads-never-split)\n\t\t\t- [2.4.1.2 AdvantageKit ordering](#2412-advantagekit-ordering)\n- [3 Project Organization](#3-project-organization)\n\t- [3.1 Commands](#31-commands)\n\t\t- [3.1.1 Organize by Subsystem](#311-organize-by-subsystem)\n\t\t- [3.1.2 Organize by Purpose](#312-organize-by-purpose)\n\t\t- [3.1.3 Autos on their Own](#313-autos-on-their-own)\n\t- [3.2 Subsystems](#32-subsystems)\n\t\t- [3.2.1 Related files](#321-related-files)\n\t- [3.3 Constants](#33-constants)\n\t\t- [3.3.1 Organize by Subsystem](#331-organize-by-subsystem)\n\t\t- [3.3.2 Organize by Topic](#332-organize-by-topic)\n\t\t- [3.3.3 Universal Constants](#333-universal-constants)\n\t- [3.4 Utilities](#34-utilities)\n- [4 Formatting](#4-formatting)\n\t- [4.1 Terminology Notes](#41-terminology-notes)\n\t- [4.2 Braces](#42-braces)\n\t\t- [4.2.1 Single-line braces are optional](#421-single-line-braces-are-optional)\n\t\t- [4.2.2 Non-empty blocks: K \\\u0026 R style](#422-non-empty-blocks-k--r-style)\n\t\t- [4.2.3 Empty blocks: may be concise](#423-empty-blocks-may-be-concise)\n\t- [4.3 Block indentation: one tab](#43-block-indentation-one-tab)\n\t- [4.4 One statement per line](#44-one-statement-per-line)\n\t- [4.5 Line Wrapping](#45-line-wrapping)\n\t- [4.6 Whitespace](#46-whitespace)\n\t\t- [4.6.1 Vertical Whitespace](#461-vertical-whitespace)\n\t\t- [4.6.2 Horizontal Whitespace](#462-horizontal-whitespace)\n\t\t- [4.6.3 Horizontal alignment: discouraged](#463-horizontal-alignment-discouraged)\n\t- [4.7 Grouping Parentheses: recommended](#47-grouping-parentheses-recommended)\n\t- [4.8 Specific Constructs](#48-specific-constructs)\n\t\t- [4.8.1 Enum classes](#481-enum-classes)\n\t\t\t- [4.8.1.1 Line breaks: keep it consistent](#4811-line-breaks-keep-it-consistent)\n\t\t\t- [4.8.1.2 Short enums: may be concise](#4812-short-enums-may-be-concise)\n\t\t- [4.8.2 Variable declaration](#482-variable-declaration)\n\t\t\t- [4.8.2.1 One variable per declaration](#4821-one-variable-per-declaration)\n\t\t\t- [4.8.2.2 Declared when needed, initialized ASAP](#4822-declared-when-needed-initialized-asap)\n\t\t- [4.8.3 Arrays](#483-arrays)\n\t\t\t- [4.8.3.1 No C-style declarations](#4831-no-c-style-declarations)\n\t\t- [4.8.4 Switch statements and expressions](#484-switch-statements-and-expressions)\n\t\t\t- [4.8.4.1 Expressions only](#4841-expressions-only)\n\t\t\t- [4.8.4.2 Default case omitted if exhaustive](#4842-default-case-omitted-if-exhaustive)\n\t\t- [4.8.5 Modifiers](#485-modifiers)\n\t\t- [4.8.6 Ternary operators](#486-ternary-operators)\n- [5 Naming](#5-naming)\n\t- [5.1 Terminology Notes](#51-terminology-notes)\n\t- [5.2 Shared rules](#52-shared-rules)\n\t- [5.3 Units](#53-units)\n\t- [5.4 Rules by identifier](#54-rules-by-identifier)\n\t\t- [5.4.1 Packages](#541-packages)\n\t\t- [5.4.2 Classes and interfaces](#542-classes-and-interfaces)\n\t\t\t- [5.4.2.1 Classes: mostly nouns](#5421-classes-mostly-nouns)\n\t\t\t- [5.4.2.2 Commands: mostly verbs](#5422-commands-mostly-verbs)\n\t\t\t- [5.4.2.3 AdvantageKit inputs: called inputs](#5423-advantagekit-inputs-called-inputs)\n\t\t\t- [5.4.2.4 IO interfaces and implementations](#5424-io-interfaces-and-implementations)\n\t\t- [5.4.3 Methods](#543-methods)\n\t\t- [5.4.4 Constants](#544-constants)\n\t\t- [5.4.5 Fields, variables, and parameters](#545-fields-variables-and-parameters)\n\t\t- [5.4.6 Type variables](#546-type-variables)\n- [6 Programming Practices](#6-programming-practices)\n\t- [6.1 Annotation usage](#61-annotation-usage)\n\t\t- [6.1.1 @Override: always used](#611-override-always-used)\n\t\t- [6.1.2 @Getter/@Setter: used when applicable](#612-gettersetter-used-when-applicable)\n\t\t\t- [6.1.2.1 Edge case: transformed data](#6121-edge-case-transformed-data)\n\t\t- [6.1.3 @AutoLogOutput: used where applicable](#613-autologoutput-used-where-applicable)\n\t- [6.2 Try/catch blocks: try to avoid](#62-trycatch-blocks-try-to-avoid)\n\t- [6.3 Static members: qualified using class](#63-static-members-qualified-using-class)\n\t- [6.4 Built-in types](#64-built-in-types)\n\t\t- [6.4.1 Numerical Values](#641-numerical-values)\n\t- [6.5 Generated files](#65-generated-files)\n\t- [6.6 Utilities](#66-utilities)\n- [7 Comments and Javadoc](#7-comments-and-javadoc)\n\t- [7.1 Comments](#71-comments)\n\t\t- [7.1.1 As often as possible](#711-as-often-as-possible)\n\t\t- [7.1.2 Minimize yapping](#712-minimize-yapping)\n\t- [7.2 Javadoc](#72-javadoc)\n\t\t- [7.2.1 Exceptions: obvious and self-explanatory members](#721-exceptions-obvious-and-self-explanatory-members)\n\t\t- [7.2.2 Eception: overrides](#722-eception-overrides)\n\n\n# 1 Introduction\n\nThis document will serve as a list of conventions and recommendations for working with WPILib Java and other libraries as a member of Team 102. This guide is heavily based on [WPILib's Java Style Guide](https://github.com/wpilibsuite/styleguide/) and our original [C++ style guide](https://github.com/FIRSTTeam102/cpp-style-guide/), with modifications based on our evolving conventions and practices. This is a guide, not a set of laws. If anything is unclear, use your best judgement and then contact the programming lead with the question. They will decide the correct styling and add it to this guide if necessary.\n\nOther teams, you are free to use, distribute, and contribute to this guide under the MIT License.\n\n## 1.1 Terminology Notes\n\nThis document will assume familiarity with the basic terminology of WPILib and the libraries Team 102 uses, including but not limited to, subsystems, commands, AdvantageKit inputs, etc. In this document, unless otherwise noted:\n\n- The term *class* refers to an \"ordinary\" class, enum, interface, annotation, record, or other extension of the common Java 'class'\n- The term comment always refers to implementation comments. We do not use the phrase \"documentation comments\", instead using the term \"[Javadoc](https://en.wikipedia.org/wiki/Javadoc).\"\n\nOther terminology notes will appear throughout the document as necessary\n\n### 1.1.1 Rule Importance Terms\n\nThe terms *must*, *can*, and *should* have special meanings in this document\n\n- A ***must*** requirement must be followed\n- A ***should*** requirement is a strong recommendation\n- A ***can*** requirement is a less strict guideline\n\n## 1.2 Guide Notes\n\nThe code in this document is **non-normative**, meaning that styling of example code in parts that aren't about the rule it is exemplifying does not have to be followed. E.g., example code formatting is not taken as a hard rule.\n\n# 2 Source File Structure\n\nA source file must consist of, in order:\n\n1. Package statement\n2. Import statements\n3. Exactly one top-level class\n\nExactly one blank line should separate each section that is present.\n\n## 2.1 Terminology\n\n- *Line wrapping*: when one line of code is split into multiple for readability purposes.\n\n## 2.2 Package Statement\n\nPackage statements must not be line-wrapped\n\n## 2.3 Import Statements\n\nImport statements must not be line-wrapped, and should be ordered as such (each group itself organized alphabetically):\n\n1. Static imports, in one group (*note:* unlike the WPILibJ guide, we allow and encourage wildcard imports in specific cases as covered in ##.##)\n2. Non-command local imports (ex: `frc.robot.subsystems.Intake`)\n3. Local command imports (ex: `frc.robot.commands.intake.SetIntakeSpeed`)\n4. WPILib package imports\n5. Vendor/3rd Party Libraries\n6. Java imports\n\n## 2.4 Class Declaration\n\nEach top-level class must reside in its own source file, named accordingly. There must be no more than one top-level class in each file. (example, the top-level class `SwerveModule` resides in `SwerveModule.java`)\n\n### 2.4.1 Class Member Ordering\n\nThe ordering of the members of a class can have a great effect on learnability, but there is no single correct recipe for how to do it. Different classes may order their members differently.\n\nWhat is important is that each class must order its members in some logical order, such its maintainer could explain if asked. For example, new methods are not just habitually added to the end of the class, as that would yield \"chronological by date added\" ordering, which is not a logical ordering.\n\n#### 2.4.1.1 Overloads: never split\n\nIf a class has an overloaded constructor or method, they must appear sequentially. If an overloaded constructor or method serves to provide default values, the constructor/method with more parameters (the more specific one) should appear first.\n\n```java\n/* more specific constructor */\npublic SetIntakeSpeed(Intake intake, double speed, boolean isIndexing) {\n\tthis.speed = speed;\n\tthis.intake = intake;\n\tthis.isIndexing = isIndexing;\n\taddRequirements(intake);\n}\n/* constructor that provides a default speed placed second */\npublic SetIntakeSpeed(Intake intake, boolean isIndexing) {\n\tthis(intake, isIndexing ? IntakeConstants.indexSpeed : IntakeConstants.intakeSpeed, isIndexing);\n}\n```\n\nIf the constructors/methods are not used for this purpose, order them in the most logical sequence.\n\n#### 2.4.1.2 AdvantageKit ordering\n\nAll 3 required declarations/initializations for AdvantageKit input logging should be placed sequentially in the following order:\n\n- Inputs class definition (as a static class)\n- Inputs object initialization\n- Definition of the updateInputs() method (as a non-static method)\n\n```java\n@AutoLog\npublic static class IntakeIOInputs {\n\tpublic double current_A = 0.0;\n\tpublic double voltage_V = 0.0;\n\tpublic double tempature_C = 0.0;\n\tpublic double percentOutput = 0.0;\n\tpublic boolean noteSensor = false;\n}\n\npublic IntakeIOInputsAutoLogged inputs = new IntakeIOInputsAutoLogged();\n\npublic void updateInputs(IntakeIOInputs inputs) {\n\tinputs.current_A = motor.getOutputCurrent();\n\tinputs.voltage_V = motor.getBusVoltage();\n\tinputs.tempature_C = motor.getMotorTemperature();\n\tinputs.percentOutput = motor.getAppliedOutput();\n\tinputs.noteSensor = !noteSensor.get();\n}\n```\n\nIf the inputs are defined within a separate IO file, the object initialization should be omitted and instead the inputs object should be initialized within the subsystem file.\n\n# 3 Project Organization\n\nAll source code (files with a `.java` extension) must be contained within `src/main/java/frc/robot`. No source files can be placed any levels up from this folder. Unless otherwise noted, this folder will be treated as the source code root folder for the rest of this section. (Example: A reference to the `/subsystems/` folder actually refers to `src/main/java/frc/robot/subsystems/`)\n\n`Main.java`, `Robot.java`, and `RobotContainer.java` must be placed directly in this directory, not in subfolders.\n\n## 3.1 Commands\n\nAny and all files completely dedicated to commands (a namespace for commands, inherit from a Command class, etc.) must be placed within the `/commands/` folder. Commands or methods that return commands which are placed within other files need not be moved into the `/commands/` folder, assuming the placement outside of the `/commands/` folder is more logical. The rest of section 3.1 will refer to commands defined within the `/commands/` folder, in their own file as the top-level class unless otherwise specified.\n\n### 3.1.1 Organize by Subsystem\n\nIf a command's main function is related to a single subsystem, such as only moving the arm or only spinning the shooter, it should be in a folder named after the subsystem in question.\n\n`/commands/intake/SetIntakeSpeed.java`, `/commands/arm/SetArmPosition.java`, `/commands/arm/ManualArmControl,java` from [2024](https://github.com/FIRSTTeam102/robot2024)\n\n### 3.1.2 Organize by Purpose\n\nIf a command's main function is related to a single purpose/action, and uses multiple subsystems in a way where one is not clearly the most relevant, it should be in a folder that relates to its purpose.\n\n`/commands/scoring/SetScoringPosition.java` from [2023](https://github.com/FIRSTTeam102/robot2023) and [2024](https://github.com/FIRSTTeam102/robot2024)\n\n### 3.1.3 Autos on their Own\n\nAutonomous routines and commands and methods only used in autonomous should be placed either in their own file (`/commands/Autos.java` or something similar), or within the folder `/commands/auto/` if there is a large number of autonomous-related commands.\n\nWhen using PathPlanner, named commands and autos should be registered in `RobotContainer.java`\n\n## 3.2 Subsystems\n\nAll files whose top-level class is a **subsystem** (either extending `SubsystemBase` or conceptually analagous to a WPILib `Subsystem`) must be placed within the `/subsystem/` folder.\n\n### 3.2.1 Related files\n\nFiles that are core to a subsystem's functionality but do not either\n\n1. Contain the main class of the subsystem; or\n2. Are not the associated constants file, as covered in section 3.3\n\nMust be placed either in a subfolder of `/subsystems/` named appropriately, or in the `/io/` folder. This decision should be made based on whatever enhances readability the most. \n\n(*NOTE*: The `/io/` folder must, as named, be exclusively used for interfaces and classes that deal with IO. IO interfaces/classes can be placed in a `/subsystems/` subfolder, but non-IO interfaces/classes cannot be placed in `/io/`)\n\n`subsystems/swerve/*.java` and `io/*VisionIO.java` from [2024](https://github.com/FIRSTTeam102/robot2024)\n\n## 3.3 Constants\n\nImportant constants such as motor IDs, PID/FF constants, enums, record definitions, etc. should be defined in a separate file contained within the `/constants/` folder. These files should deal with a specific portion of the general code only and be named accordingly, with the format `**SUBJECT**Constants.java`, where \\*\\*SUBJECT** is a single, capitalized noun to describe the file. What the \\*\\*SUBJECT** is will be described in the following rules.\n\n### 3.3.1 Organize by Subsystem\n\nIf constants are related by a common subsystem, they should all be placed in a file named after the subsystem\n\n`constants/IntakeConstants.java`, `constants/ShooterConstants.java` from [2024](https://github.com/FIRSTTeam102/robot2024)\n\n### 3.3.2 Organize by Topic\n\nIf constants are related by a common topic, they should be placed in a file named after that topic\n\n`constants/ScoringConstants.java` from [2024](https://github.com/FIRSTTeam102/robot2024)\n\n### 3.3.3 Universal Constants\n\nOne file, `constants/Constants.java`, should contain constants that are relevant to the entire robot, not a specific subsystem/topic.\n\n## 3.4 Utilities\n\nClasses, static methods, and more that have utility functionality that are generally relevant to the robot should be placed within the `/util/` folder. There is no specific naming convention for the files/classes contained within this folder.\n\n# 4 Formatting\n\n## 4.1 Terminology Notes\n\n- Braces: `{}`\n- Brackets: `[]`\n- Block-like construct: the body of a class, method or constructor.\n- Logical units: Multiple lines of code that fit together logically or contextually.\n- Horizontal alignment: Adding extra whitespace to lines to make certain tokens appear below other tokens\n\n```java\n// No alignment\nprivate int x;\nprivate String str;\n\n// alignment\nprivate int    x;\nprivate String str;\n```\n\n## 4.2 Braces\n\n### 4.2.1 Single-line braces are optional\n\nSingle-line `if`, `else`, `for`, `do`, and `while` statements can have their braces ommitted if it enhances readability.\n\n### 4.2.2 Non-empty blocks: K \u0026 R style\n\nBraces follow the K \u0026 R style for *non-empty* blocks and block-like constructs:\n\n- No line break before the opening brace\n- Line break after the opening brace\n- Line break before the closing brace.\n- Line break after the closing brace if that brace terminates a statement or the body of a method, constructor or named class. For example, there is no line break after the brace if it is followed by else or a comma.\n\n```java\npublic class TestClass {\n\tpublic static void method(boolean condition) {\n\t\tif (condition) {\n\t\t\tdoSomething();\n\t\t} else {\n\t\t\tdoSomethingElse();\n\t\t}\n\t}\n}\n```\n\n### 4.2.3 Empty blocks: may be concise\n\nAn empty block or block-like construct may be closed immediately after being opened, with no spaces or line breaks in-between the braces.\n\n```java\npublic void doNothing() {}\n```\n\n## 4.3 Block indentation: one tab\n\nEach time a new block or block-like construct is opened, the indent increases by one tab. When the block ends, the indent decreases by one tab, as seen in the 4.2.2 example.\n\n## 4.4 One statement per line\n\nEvery statement must be followed by a line break.\n\n## 4.5 Line Wrapping\n\nStatements that are very long should be line-wrapped to enhance readability. Each line after the first in a line-wrapped statement should be indented with the standard one tab as described in 4.3.\n\n## 4.6 Whitespace\n\n### 4.6.1 Vertical Whitespace\n\nA single blank line should appear between *logical units* of code. Spacing out code by logical units helps to improve readability and reduce clutter.\n\n### 4.6.2 Horizontal Whitespace\n\nAside where required by Java, a single space must appear in the following situations **only**:\n\n1. Separating any reserved word, such as `if`, `for` or `catch`, from an open parenthesis (`(`) that follows it on that line\n2. Separating any reserved word, such as `else` or `catch`, from a closing curly brace (`}`) that precedes it on that line\n3. Before any open curly brace (`{}`), with two exceptions:\n\t- `@SomeAnnotation({a, b})` (no space is used)\n\t- `String[][] x = {{\"foo\"}};` (no space is required between `{{` or `}}`, by item 8 below)\n4. On both sides of any binary or ternary operator. This also applies to the following \"operator-like\" symbols\n\t- the ampersand in a conjunctive type bound: `\u003cT extends Foo \u0026 Bar\u003e`\n\t- the pipe for a catch block that handles multiple exceptions: `catch (FooException | BarException e)`\n\t- the colon (`:`) in an enhanced `for` (\"foreach\") statement\n5. After `,`, `:`, or `;` or the closing parenthesis of a typecast (`)`)\n6. After the double slash (`//`) that begins a single line or end-of-line comment.\n7. Between the type and variable of a declaration `List\u003cString\u003e list` \n8. *Optional* inside both braces of an array initializer\n\t- `new int[] {5, 6}` and `new int[] { 5, 6 }` are both valid\n\n### 4.6.3 Horizontal alignment: discouraged\n\nHorizontal alignment is generally discouraged, and may only be used if it substantially increases the readability of the code.\n\n## 4.7 Grouping Parentheses: recommended\n\nOptional grouping parentheses are omitted only when author and reviewer agree that there is no reasonable chance the code will be misinterpreted without them, nor would they have made the code easier to read. It is not reasonable to assume that every reader has the entire Java operator precedence table memorized.\n\n## 4.8 Specific Constructs\n\n### 4.8.1 Enum classes\n\nSince enum classes are classes, all other rules for formatting classes apply, but there are specific rules for enums:\n\n#### 4.8.1.1 Line breaks: keep it consistent\n\nFor a given enum class, there can be a line break following the comma after each enum constant, or no line-breaks at all. Do not mix and match in one enum declaration, and no more than one line break per constant.\n\n```java\n/* compliant with 4.8.1.1 */\npublic enum Suit { \n\tClubs, Hearts, Spades, Diamonds \n}\n\n/* also compliant */\npublic enum Suit {\n\tClubs,\n\tHearts,\n\tSpades,\n\tDiamonds\n}\n\n/* not compliant */\npublic enum Suit {\n\tClubs, Hearts,\n\tSpades,\n\tDiamonds\n}\n```\n\n#### 4.8.1.2 Short enums: may be concise\n\nAn enum with no methods and no documentation on its constants may be formatted like an array initializer\n\n```java\n/* OK */\npublic enum Suit {\n\tClubs, Hearts, Spades, Diamonds\n}\n\n/* also OK */\npublic enum Suit { Clubs, Hearts, Spades, Diamonds }\n```\n\n### 4.8.2 Variable declaration\n\n#### 4.8.2.1 One variable per declaration\n\nEvery variable declaration (field or local) declares only one variable: declarations such as `int a, b;` are not used.\n\n#### 4.8.2.2 Declared when needed, initialized ASAP\n\nLocal variables must **not** be habitually declared at the start of their containing block or block-like construct. Instead, local variables should be declared close to the point they are first used (within reason) to minimize their scope. Local variable declarations should have initializers, or be initialized immediately after declaration.\n\n### 4.8.3 Arrays\n\nArrays must be declared with the same formatting as [enums](#4811-line-breaks-keep-it-consistent).\n\n```java\n/* OK */\nnew int[] {0, 1, 2, 3};\n\nnew int[] {\n\t0, 1, 2, 3\n};\n\nnew int[] {\n\t0,\n\t1,\n\t2,\n\t3\n};\n\n/* not OK */\nnew int[] {\n\t0, 1,\n\t2, 3\n};\n```\n\n#### 4.8.3.1 No C-style declarations\n\nSquare brackets must be a part of the *type*, not the variable name. `String[] args`, not `String args[]`.\n\n### 4.8.4 Switch statements and expressions\n\n#### 4.8.4.1 Expressions only\n\nThe modern switch expression syntax must be used instead of the classic switch statement syntax.\n\n```java\n/* Statements: NOT ok */\nswitch (alliance.get()) {\n\tcase Red:\n\t\tredAllianceFunc();\n\t\tbreak;\n\tcase Blue:\n\t\tblueAllianceFunc();\n\t\tbreak;\n\tdefault:\n\t\tbreak;\n}\n\n/* Expressions: OK */\nswitch (alliance.get()) {\n\tcase Red -\u003e redAllianceFunc();\n\tcase Blue -\u003e blueAllianceFunc();\n}\n```\n\n#### 4.8.4.2 Default case omitted if exhaustive\n\nThe `default` case expression group may be omitted if the switch statement covers all possible values of the input (e.g., is exhaustive)\n\n### 4.8.5 Modifiers\n\nClass and member modifiers, when present, appear in the order recommended by the Java Language Specification\n\n```java\npublic protected private abstract static final transient volatile synchronized native strictfp\n```\n\n### 4.8.6 Ternary operators\n\nThe ternary operator should be used for any conditional statement with simple expressions (simple operations, return value switch, etc.). Ternary operators may not be nested.\n\n# 5 Naming\n\n## 5.1 Terminology Notes\n\n- `camelCase`: Each word has its first letter capitalized. The first word is not capitalized. There are no underscores or other characters between words.\n- `PascalCase`: Same as camelCase, but the first word is capitalized.\n- descriptor: An extra word or abbreviation placed after an underscore after the name. For the purposes of this guide, the name and descriptor are considered separate items within the entire identifier, in the form `\u003cname\u003e_\u003cdescriptor\u003e`. Descriptors are all lowercase and limited to a single word or abbreviation.\n  \n## 5.2 Shared rules\n\nIdentifiers use only ASCII letters and digits, and in specific cases described below, underscores.\n\n## 5.3 Units\n\nFields, variables, parameters, and other related constructs that have units associated with them must have those units as a descriptor. This is to reduce confusion between units that describe the same physical quantity (feet/s vs m/s, etc.). Use standard abbreviations, and to conform with [5.2](#52-shared-rules), the word 'per' (as in 'feet per second') should be replaced with a `p` in the abbreviation ('feet per second' becomes `ftps`, not `ft/s`).\n\n```java\n/* Good examples */\ndouble voltage_V; // Volts\n\ndouble velocity_mps; // Meters per second\n\ndouble velocity_rpm; // Rotations per minute\n\ndouble position_ft; // Feet\n\n/* bad examples */\ndouble voltage; // no unit, even though may be obvious\n\ndouble voltage_millivolts; // not abbreviated, should be mV\n```\n\n## 5.4 Rules by identifier\n\n### 5.4.1 Packages\n\nPackage names are all lowercase, with separate words concatenated together. `com.example.deepspace`, not `com.example.deepSpace`\n\n### 5.4.2 Classes and interfaces\n\nClass and interface names must be written in PascalCase\n\n#### 5.4.2.1 Classes: mostly nouns\n\nSubsystems, records, enums, data classes, utilities, and most other classes should generally be named with nouns, such as `Shooter`, `ArmConstants`, `ScoringPosition`, etc.\n\n#### 5.4.2.2 Commands: mostly verbs\n\nCommands that have a name (e.g., not inline) should generally be named with verbs, such as `SetScoringPosition` or `IntakeWithArm`, but may be named with other terms if more applicable, such as `ManualArmControl` or `XStance`.\n\n#### 5.4.2.3 AdvantageKit inputs: called inputs\n\nAdvantageKit inputs classes must be named with the name of their enclosing class, with `Inputs` appended at the end, such as `ShooterInputs` and `FieldVisionInputs`.\n\n*(**NOTE**: the 2023 and 2024 robot code currently does not comply with this rule, with the suffix instead being `IOInputs`. Continue to use this non-compliant suffix or update all other inputs class names within these projects to maintain consistency.)*\n\n#### 5.4.2.4 IO interfaces and implementations\n\nInterfaces that lay out IO implementations or classes that define IO must have their name suffixed with `IO`, such as `SwerveModuleIO` or `FieldVisionIO`.\n\nThe implementations of IO Interfaces must have their name be the interface they are implementing suffixed with a descriptor of the implementation. There are no specific guidelines for this descriptor. Examples include `SwerveModuleIOReal`, `GyroIOPigeon2`, and `SwerveModuleIOSim`.\n\n### 5.4.3 Methods\n\nMethod names must be written in camelCase, and are generally verbs or verb phrases.\n\nMethod identifiers may share names but have descriptors to describe their implementation, such as `estimateScoringPosition_math` and `estimateScoringPosition_map`.\n\n### 5.4.4 Constants\n\nSince constants reside in their own file, it is relatively obvious when something is a constant or not, and thus they do not require a prefix or other unique characteristic. They should be named just like variables and fields.\n\n### 5.4.5 Fields, variables, and parameters\n\nFields, variables, and parameters must be in camelCase, and should generally be nouns or noun phrases.\n\nOne character variable names should be avoided, except for very temporary and specific looping variable. If a multi-character name can be used without hurting readability, it should be used.\n\n### 5.4.6 Type variables\n\nEach type variable is named in one of two styles:\n\n- A single capital letter, optionally followed by a single numeral (such as `E`, `T`, `X`, `T2`)\n- A name in the form used for classes (see [5.4.2](#542-classes-and-interfaces)), followed by the capital letter T (examples: `RequestT`, `FooBarT`).\n\n# 6 Programming Practices\n\n## 6.1 Annotation usage\n\nA general rule of thumb is that, whenever an annotation can be used in a way to reduce code clutter, it should be used. Of course, readability is prioritized, and if an annotation will make a piece of code *more* difficult to read, its use should be discarded.\n\n### 6.1.1 @Override: always used\n\nA method is marked with the `@Override` annotation whenever it is legal. This includes a class method overriding a superclass method, a class method implementing an interface method, and an interface method respecifying a superinterface method.\n\n### 6.1.2 @Getter/@Setter: used when applicable\n\nPrivate member variables with getter and setter methods must have those methods defined with the `@Getter` and `@Setter` annotations provided by lombok\n\n```java\n/*Compliant with 6.1.2*/\n@Getter\nprivate double readOnlyValue = 0.0;\n\n/*Non-compliant with 6.1.2*/\nprivate double readOnlyValue = 0.0;\n\npublic double getReadOnlyValue() {\n\treturn readOnlyValue;\n}\n```\n\n#### 6.1.2.1 Edge case: transformed data\n\nGetter and setter methods that transform the data in some way or perform some side-effect are exempt from rule [6.1.2](#612-gettersetter-used-when-applicable), and should be placed in their own methods for readability.\n\n### 6.1.3 @AutoLogOutput: used where applicable\n\nWhen a field should be logged as-is as a RealOutput in AdvantageKit, the `@AutoLogOutput` annotation should be used rather than `Logger.recordOutput()` being called in `periodic()`.\n\n```java\npublic class Example extends SubsystemBase {\n\t/* compliant with 6.1.3 */\n\t@AutoLogOutput\n\tprivate double loggedOutput = 0.0;\n\n\t/* not compliant */\n\tprivate double loggedOutput2 = 0.0;\n\t@Override\n\tpublic void periodic() {\n\t\tLogger.recordOutput(\"Example/loggedOutput2\", loggedOutput2);\n\t}\n}\n```\n\n## 6.2 Try/catch blocks: try to avoid\n\nTry/catch blocks are only permitted if there is no other way to do something. In all other cases, they should be avoided.\n\n(***NOTE:*** *if you are tempted to use a try/catch block, think deeply about whether you should be doing what you're trying to do in the first place. Only after going through this process multiple times should you ever entertain the thought of using one.*)\n\n## 6.3 Static members: qualified using class\n\nWhen a reference to a static class member must be qualified, it is qualified with that class's name, not with a reference or expression of that class's type.\n\n```java\nFoo aFoo = ...;\n\nFoo.aStaticMethod(); // good\naFoo.aStaticMethod(); // bad\nsomethingThatYieldsAFoo().aStaticMethod(); // very bad\n```\n\n## 6.4 Built-in types\n\nWPILib uses `int` for user-facing interfaces instead of `byte` to avoid casts. \n\n### 6.4.1 Numerical Values\n\nJava's default data type for all numerical values which include a decimal (i.e. 24.5) is `double`, which should be used instead of `float` for consistency unless absolutely necessary. \n\n**IMPORTANT:** ALWAYS include a decimal place when entering a numerical value within a `double`, and especially when performing calculations within a double. For example `1/21` should be entered as `1.0/21.0`. This is because Java will identify a whole number without a decimal as an integer (type `int`) by default, which may result in errors in calculation - in the examples above, `1/21` results in the value of `0` (zero) where we would most likely prefer the result of `1.0/21.0` which produces `0.0476190476190476`. \n\n## 6.5 Generated files\n\nSince changes would be overwritten upon regeneration, generated files such as `BuildConstants.java` and `*.auto` files must not be manually edited.\n\n## 6.6 Utilities\n\nAs noted in [3.4](#34-utilities), any utility methods, classes, etc. should be placed within an appropriately named file in the `/utils/` directory. Creation of utilities is recommended, and any general methods that do not have direct relation with a subsystem or command should be categorized as utilities.\n\n# 7 Comments and Javadoc\n\n## 7.1 Comments\n\nComments should generally be full line or end-of-line with double slashes (`//`). \n\n### 7.1.1 As often as possible\n\nWhenever the implementation of a method is anything less than incredibly obvious/self-explanatory, or additional notes need to be provided for future reviewers, descriptive comments must be added. Implementation comments should accurately walk through the thought process and program flow in a given implementation, so that a future reviewer can get into the original developer's mindset.\n\n### 7.1.2 Minimize yapping\n\nExtraneous comments, jokes, self-deprecation, and more are not permitted to be part of any comments. Implemetation comments and comments that provide helpful notes should be concise and professional, without extraneous language.\n\n## 7.2 Javadoc\n\nAt the *minimum*, Javadoc is present for every `public` class, and every `public` or `protected` member of a class, with a few exceptions noted below.\n\nOther classes and methods still have Javadoc as needed. Whenever an implementation comment would be used to define the overall purpose or behavior of a class, method or field, that comment is written as Javadoc instead. (It's more uniform, and more tool-friendly.)\n\n### 7.2.1 Exceptions: obvious and self-explanatory members\n\nJavadoc is optional for simple, obvious methods like getters and setters, where there `really and truly` is nothing better to say than \"Returns the thing\".\n\n*(**NOTE:**) It is not appropriate to cite this exception to justify omitting relevant information that a typical reader might need to know. For example, for a method named `getCanonicalName`, don't omit its documentation (with the rationale that it would say only `/** Returns the canonical name. */`) if a typical reader may have no idea what the term \"canonical name\" means!*\n\n### 7.2.2 Eception: overrides\n\nJavadoc does not need to be present on a method that overrides a supertype method.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstteam102%2Fjava-style-guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirstteam102%2Fjava-style-guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirstteam102%2Fjava-style-guide/lists"}