4.2 KiB
Sample Class/Opmode conventions
V 1.1.0 8/9/2017
This document defines the FTC Sample OpMode and Class conventions.
OpMode Name
To gain a better understanding of how the samples are organized, and how to interpret the naming system, it will help to understand the conventions that were used during their creation.
To summarize: A range of different samples classes will reside in the java/external/samples. The class names will follow a naming convention which indicates the purpose of each class. The prefix of the name will be one of the following:
Basic: This is a minimally functional OpMode used to illustrate the skeleton/structure of a particular style of OpMode. These are bare bones examples.
Sensor: This is a Sample OpMode that shows how to use a specific sensor. It is not intended to drive a functioning robot, it is simply showing the minimal code required to read and display the sensor values.
Robot: This is a Sample OpMode that assumes a simple two-motor (differential) drive base. It may be used to provide a common baseline driving OpMode, or to demonstrate how a particular sensor or concept can be used to navigate.
Concept: This is a sample OpMode that illustrates performing a specific function or concept. These may be complex, but their operation should be explained clearly in the comments, or the comments should reference an external doc, guide or tutorial. Each OpMode should try to only demonstrate a single concept so they are easy to locate based on their name. These OpModes may not produce a drivable robot.
After the prefix, other conventions will apply:
- Sensor class names should constructed as: Sensor - Company - Type
- Robot class names should be constructed as: Robot - Mode - Action - OpModetype
- Concept class names should be constructed as: Concept - Topic - OpModetype
Sample OpMode Content/Style
Code is formatted as per the Google Style Guide:
https://google.github.io/styleguide/javaguide.html
With “Sensor” and “Hardware” samples, the code should demonstrate the essential function, and not be embellished with too much additional “clever” code. If a sensor has special addressing needs, or has a variety of modes or outputs, these should be demonstrated as simply as possible.
Special programming methods, or robot control techniques should be reserved for “Concept” Samples, and where possible, Samples should strive to only demonstrate a single concept, eg: State machine coding, or a User Menu system, and not combine them into a single “all inclusive” sample. This will prevent an “all inclusive” Sample being deleted just because one part of it becomes obsolete.
Device Configuration Names
The following device names are used in the external samples
** Motors: left_drive right_drive left_arm
** Servos: left_hand right_hand arm claw
** Sensors: sensor_color sensor_ir sensor_light sensor_ods sensor_range sensor_touch sensor_color_distance sensor_digital digin digout
** Localization: compass gyro imu navx
Device Object Names
Device Object names should use the same words as the device’s configuration name, but they should be re-structured to be a suitable Java variable name. This should keep the same word order, but adopt the style of beginning with a lower case letter, and then each subsequent word starting with an upper case letter.
Eg: from the examples above: tool, leftMotor, rightClawServo, rearLightSensor.
Note: Sometimes it’s helpful to put the device type first, followed by the variant. eg: motorLeft and motorRight, but this should only be done if the same word order is used on the device configuration name.
OpMode code Comments
Sample comments should read like normal code comments, that is, as an explanation of what the sample code is doing. They should NOT be directives to the user, like: “insert your joystick code here” as these comments typically aren’t detailed enough to be useful. They also often get left in the code and become garbage.
Instead, an example of the joystick code should be shown with a comment describing what it is doing.