Conventions

This repository contains guidelines for developing any future Horace Greeley robotics. The repository contains structural and architectural guidelines as well as linting preferences. If any formatting and/or guideline changes in the future, please update this repository.

Table of Contents

• Java source files
  • Naming
  • Comments
  • Indentation
    • Wrapping lines
  • Declarations
  • White space
  • Misc
  • Source
• Version control
  • Branching
  • CI/CD
  • Commit conventions
  • Merge reviews
• IDE
  • Plugins
  • Tutorials

Java source files

Minimal ruleset with the most important guidelines.

Naming

Variable names must be mnemonic. All variables should be written in camelCase style. Constants are in uppercase and separated by underscores. Any class or interface should start in uppercase and continue in lowercase such as "ImageSprite". Packages should be written in all lowercase ASCII letters. Methods should be written in camelCase style

Comments

Please do not use inline comments. Use the asterisk styled /* comment */ comment even for one-line comments. File header comments should be automatically generated by plugins or other tools.

Indentation

Tab characters are not used for indentation. The indentation should be 2 spaces. Avoid lines longer than 80 characters.

Wrapping lines

• Break after comma
• Break before operator (e.g. +, *)
• Align the new line with the beginning of the expression in the previous line (or if this leads to too squished code just indent 4 spaces)

Declarations

Please use one declaration per line. (e.g. int width; and NOT int width, height;)

White space

Use two line blanks in the following cases:

• Between file header comments and package/import statements
• Between two classes/interfaces

Use one line blank in the following cases:

• Between methods
• Between local variables in the method and its first statement
• Before any comment
• Between two logical sections in a method (should be rare, use two methods instead)
• Between package and import statements

Use a single blank space in the following cases:

• After comma
• On both sides of an operator
• Between cast and variable
• Between keyword and parenthesis
• Between for statement expressions (e.g. for (expr1; expr2; expr3) {})
• Between parenthesis and curly brackets in almost all cases (e.g. while (true) {})

Misc

A line should not be complex. One statement, one line. An if should always have braces. A source file should only have one interface/class except for encapsulated classes.

Source

Most of these rules/guidelines are defined at Google. If something is unclear please default to Google's Java conventions.

Version control

Horace Greeley High School Robotics uses git as its primary version manager.

Each unique codebase should have a separate repository.

Branching

We use primarily branching instead of tags. Each production codebase should have a developer (dev) a testing (test) and a stable (stable) branch. Always set the default branch to dev. You should always use the dev branch to update, push or modify code. Never push into higher-level (test or stable) branches. The only way to update such branches is with a reviewed merge. You can move up semi-stable code from the dev to test but never two steps at a time. You can only move up well-tested code from test to stable. Any new branch can only be merged into the dev branch. Branch names have to be lowercase and hyphen separated. Do not have trailing or continuous hyphens. The branch name should only include alphanumeric characters and have a descriptive name.

CI/CD

For any CI/CD operation, we use Github's built-in Actions.

Commit conventions

A commit message should be a maximum of 72 characters. Commit messages should be always imperative. Always capitalize and start the commit message with a verb (e.g. Add, Change, Fix, Remove) Describe what you changed/added.

Merge reviews

Every branch should be protected by rules through Github. A pull request is required for every merge attempt. At least one review is required to merge a branch.

IDE

We are using Visual Studio Code as our default IDE simply because it already has a WPILib plugin. The plugin exposes templates, ways to build the software and more making it very easy for newbies and beginners to immediately start coding. BEWARE: We do not recommend using any other IDE/Editor. If you are, it is your responsibility to set it up correctly. This is not a simple task as WPILib is not extensively supported.

Plugins

We use the following plugins in VSCode:

• Extension Pack for Java by Microsoft
• C/C++ Extension Pack by Microsoft
• WPILib Java Snippets by WPILib (Official)
• markdownlint by David Anson (follow markdown linting guidelines)
• Grammarly by Rahul Kadyan (useful when editing docs)
• GitHub Actions by GitHub

Additionally, check whether you have the WPILib plugin installed. It should be installed by the FRC installer described here. If you have any issues please raise an issue in the installation repository or look at already answered ones.

Tutorials

Here are some tutorials to get started with using the IDE:

• VSCode Tutorial For Beginners - Getting Started With VSCode
• Using Git with Visual Studio Code (Official Beginner Tutorial)
• WPILib VS Code Introduction - WPILib FRC Java Programming Tutorial Video 2