Code Formatting and Conventions

File/directory names

These rules don't apply to external rospackages that we depend on.

• Python: snake_case
• Bash: snake_case
• HTML/CSS/JS: PascalCase
• Arduino/C/C++: PascalCase
• Arduino Project Directories: PascalCase
• All other directories: snake_case
• Media Files: snake_case

JavaScript

We follow the standard conventions, there exists an auto-formatter package in atom called atom-standard-formatter which automates this.

Formatting Guide (Python)

When you install the requirements-dev.txt. dependencies, you will have pylint and yapf installed. Both of these packages allow for set guidelines on how code should behave (pylint) and how it should look (yapf). In other words, pylint is the project's linter and yapf is the auto-formatter. You can read more about these online but the basic principle is that we should all have code that looks alike and behaves properly based on some established set of heuristics. The .pylint file (based entirely on Google's very own one) contains the configurations that pylint uses to validate the code. If you configure your IDE properly, both the linter (pylint) and autoformatter (yapf) should work without prompting any action. Here is an example of the project opened in VSCode (which has it's configurations outlined in .vscode/settings.json) showing how pylint indicates things (also shown clickable pytest actions right inside the source!):

You might not be able to tell from the screenshot, but whenever the incorrect indentation or needless linebreaks are entered, yapf automatically formats the code to comply with the project's format rules.

All in all, by using these tools, we will ensure that the codebase is consistent is less of a pain to maintain in the long run or for any new entrants.

Although most of the syntax/format will be handled by pylint/yapf, some things that aren't are briefly outlined here (namely regarding source file naming guidelines):

• As stated here, file names shouldn't include dashes since they need to be importable.
• Although class names use CapWords, modules should have lower_with_under.py names. This is to prevent confusing with imports on whether or not the module itself or the class was imported as described here. This means even if you file contains only one class like Motor, the filename (i.e. module name -- each Python file is considered a module) should be motor.py and not Motor.py.
• Test files should be named modulename_test.py (note the _test appearing as a suffix, not prefix) with the class inside named TestModuleName (here Test needs to be a prefix, blame pytest for that). This class should encapsulate the methods that test various functionality or states named test_<functionality_or_state>(self) (same for functions). Note that these guidelines will ensure that your tests will be recognized by pytest's test discovery.