Comments and documentation

Reasons and constraints

A comment is useful when a teammate needs to know why the code uses a value or takes an unusual step. It is less useful when it only repeats the line below it.

The second column gives context a reader cannot infer from setPower or setDirection alone. Keep the comment near the code it explains.

Units and assumptions

Measurements are easy to misuse when their units or starting point are unclear:

// Encoder zero is set with the arm resting against its mechanical stop.
// This limit is in encoder ticks, not degrees.
private static final int ARM_UPPER_LIMIT_TICKS = 850;

The value 850 is only an illustration. Your team must measure its own safe limit. A comment should record how a number was chosen, but it cannot replace testing.

Method documentation

When teammates call a method from several OpModes, describe what they can pass and what the method guarantees:

/**
 * Sets arm motor power, limited to the tested range [-0.25, 0.25].
 * Call with zero when manual arm control should stop.
 */
public void moveArm(double requestedPower) {
    double safePower = Math.max(-0.25, Math.min(0.25, requestedPower));
    armMotor.setPower(safePower);
}

This fragment assumes armMotor has already been mapped. It is not a complete OpMode.

Comment maintenance

• Update a comment when behavior changes. A wrong comment can be worse than no comment.
• Use TODO for a specific future task, such as // TODO: Add a timeout to the homing routine before field testing. Do not leave an unsafe loop in use just because it has a TODO.
• Delete commented-out code once the team has a working replacement in Git history.
• Put setup steps, robot configuration names, and test instructions in a short README instead of repeating them in every file.

Review checklist

Read a comment without looking at the code beneath it. Does it explain a decision, unit, constraint, or expected behavior? If it only narrates syntax, improve the name or remove the comment.

Next steps

See team collaboration for how to review and share these changes.