Software Standards

Version: v2025.0
Owner: Software Lead
Last Updated: 2025-11-27
Reviewed: No
Deviations Allowed: Yes (with approval)

Why: predictable structure, safer changes, and better debugging. Keep code releasable and testable.

Project structure

• Command-based layout, packages, naming, subsystem/command patterns.

Practices

• Logging/replay (AdvantageKit or similar), code review expectations, linting/formatting.

Controls

• Sensor selection, units, coordinate frames, safety interlocks, watchdogs.

Visual/example

• Diagram of data flow (controller → commands → subsystems → IO).

Common failure modes

• Unit mismatches, unhandled null targets, blocking calls, missing requirements on commands.

Instructions (numbered)

1. Use command-based structure with clear packages and naming; set defaults and requirements.
2. Enforce lint/format; use code review for all merges; keep vendordeps versioned.
3. Implement logging/replay; document NetworkTables keys and units.
4. Validate units and coordinate frames; clamp outputs; handle null/invalid targets.
5. Test in sim before robot; add checklists for pre-field (logging on, controls mapped, autos selected).

Best practices

• Declare requirements on commands to avoid resource conflicts.
• Keep commands small and composable; avoid blocking/sleeping.
• Log critical signals; capture build info and versions.
• Use safety interlocks for actuators; fail safe on comms loss.

Common mistakes

• Unit mismatches; missed requirements; blocking code in commands.
• No logging; broken dashboards due to missing NT keys/units.
• Vendordeps not pinned; controller mapping differences.

Checklist

• Command-based structure, naming, requirements
• Lint/format passed; code reviewed
• Vendordeps versioned and committed
• Logging/replay configured; NT keys/units documented
• Sim run passes; pre-field checklist ready

Recommended tools

• WPILib + Sim GUI, logging (AdvantageKit/WPILib data log), lint/format tool (spotless/eslint), CI for builds/tests.

Sample log (template)

• Date:
• Changes:
• Sim/Tests run:
• Issues:
• Next steps:

Photos/diagrams

• [Placeholder: data flow diagram controller → commands → subsystems → IO/logging]

Deviations

Deviations from these standards are permitted only with written justification and documentation.
All deviations must include: subsystem, rationale, supporting data, and date.

Specification Table

Category	Standard
Units	meters, meters/sec, meters/sec²
Coordinate Frames	robot-centric
Sensor Units	ticks → meters
Naming	camelCase for vars, PascalCase for classes
Logging	voltage, current, pose, velocity, error
Filesystem Layout	src/main/java/...

Example Values

Path constraints:

• Max velocity: 3.0 m/s
• Max accel: 2.5 m/s²

Control constants:

• kS: 0.13 V
• kV: 1.41 V/(m/s)
• kA: 0.09 V/(m/s²)

Vision latency:

• Typical: 30–45 ms

Sources

• WPILib: docs.wpilib.org/en/stable/index.html
• Limelight: limelightvision.io
• YAGSL Swerve: github.com/Mechanical-Advantage/YAGSL

See also:

• Glossary
• Subsystem Templates

📘 Reference the Glossary for definitions of common terms and constraints.