Instructional Material: Example of well-commented code

#pragma config(Sensor, S2,     lightSensor,         sensorLightActive)
#pragma config(Motor,  motorB,          ,              tmotorNormal, PIDControl)
#pragma config(Motor,  motorC,          ,              tmotorNormal, PIDControl)
//*!!Code automatically generated by 'ROBOTC' configuration wizard               !!*//

///////////////////////////////////////////////////////////////////////////////
//                                InclinePlane                               //
//                                                                           //
//                         by Nick Nguyen & John Aguilar                     //
//                                                                           //
// ToDo: Add class name, date, instructor name and assignment title here.    //                                                                          //
//                                                                           //
// We went into the Motor and Sensor Setup wizard and configured our drive   //
// motors and the light sensor.                                              //
//                                                                           //
// The above #pragmas need to stay at the top of the file or RobotC will not //
// find them. You should not add #pragmas manually. You should always use    //
// the Motor and Sensor Setup wizard.                                        //
//                                                                           //
// This program is suppose to make our robot go up an incline plane, touch   //
// the top line and come back, touch the bottom line, and repeat this three  //
// times before back down and stopping on the platform.                      //
//                                                                           //
///////////////////////////////////////////////////////////////////////////////

#define lightSensorWhiteValue   55   // Value of the light sensor on a white surface
#define lightSensorDarkValue    15   // Value of the light sensor on a dark surface

// Compute the threshold value half way between the light and dark readings:
#define lightSensorThreshold    ((lightSensorWhiteValue + lightSensorDarkValue)/2)

///////////////////////////////////////////////////////////////////////////////
// To figure out the number you should set for your light sensor threshold,  //
// set the sensor on a white surface, set lightSensorWhiteValue to the value,//
// and then set it on a dark piece of tape and set lightSensorDarkValue to   //
// that value. This is so the robot can distinguish when to proceed with     //
// each step of the program.                                                 //
//                                                                           //
// The light sensor threshold value is the average of the numbers you had    //
// recorded for the dark and light values.                                   //
//                                                                           //
// ToDo: At the start of the program we should prompt the user to place the  //
//       robot on a White surface and press a button. Then we should prompt  //
//       them to place the robot on a dark surface and press the button.     //
//       We should replace the #defines for lightSensorWhiteValue and        //
//       lightSensorDarkValue with global variables and initialize them to   //
//       the value of the light sensor after each button press.              //
//                                                                           //
///////////////////////////////////////////////////////////////////////////////

// Wait1Sec
//
// Easier to read than calling wait1Msec with big numbers.
void inline Wait1Sec(int sec)
{
    wait1Msec(sec * 1000);
}

// beginning of program //
task main()
{

    // PASS NUMBER ONE of three //

    // Start moving up the ramp at full speed for a while.
    motor[motorC] = 100;
    motor[motorB] = 100;
    Wait1Sec(2);

    // Now keep going until we see the line at the top of the ramp.
    while(SensorValue(lightSensor) > lightSensorThreshold)
    {
        motor[motorC] = 100;
        motor[motorB] = 100;
    }

    // Now start to slowly back down the ramp.
    motor[motorC] = -25;
    motor[motorB] = -25;
    Wait1Sec(1);

    // Keep going until we see the line at the bottom.
    while(SensorValue(lightSensor) > lightSensorThreshold)
    {
        motor[motorC] = -25;
        motor[motorB] = -25;
    }

    // At this point we have completed one pass up and down the ramp. We need //
    // do it twice more. Instead of looping the program, we copied and pasted //
    // the same exact part of the program from the top to make the robot do   //
    // the exact same thing. //

    // ToDo: Replace this with a FOR loop. //

    // PASS NUMBER TWO of three //

    // UP the ramp
    motor[motorC] = 100;
    motor[motorB] = 100;
    Wait1Sec(1);

    // Find the top line
    while(SensorValue(lightSensor) > lightSensorThreshold)
    {
        motor[motorC] = 100;
        motor[motorB] = 100;
    }

    // Down the ramp
    motor[motorC] = -25;
    motor[motorB] = -25;
    Wait1Sec(1);

    // Find the bottom line
    while(SensorValue(lightSensor) > lightSensorThreshold)
    {
        motor[motorC] = -25;
        motor[motorB] = -25;
    }

    // PASS NUMBER THREE of three //

    // Up the ramp
    motor[motorC] = 100;
    motor[motorB] = 100;
    Wait1Sec(1);

    // Find the top line
    while(SensorValue(lightSensor) > lightSensorThreshold)
    {
        motor[motorC] = 100;
        motor[motorB] = 100;
    }

    // The robot has hit the top line for the 3rd time.              //
    // Back all the way off the incline plane and off the platform.  //
    // There is no need to look for the bottom line again.           //
    motor[motorC] = -50;
    motor[motorB] = -50;
    Wait1Sec(1);
}

// end of program //