Activity 7: Constants and Comments

The next sketch, CountToTenDocumented, is different from CountToTen in several ways.  First, it has a block comment at the top.  A block comment starts with /* and ends with */, and you can write as many lines of notes in between as you want.  Also, each line of code has a line comment (starting with // ) to its right, explaining what the code does. 

Last, two const int (constants that are integers) are declared at the beginning of the sketch,  giving the names startVal, endVal, and baudRate to the values 1, 10, and 9600.  Then, the sketch uses these names wherever it requires these values.

/*
 Robotics with the BOE Shield – CountToTenDocumented
 This sketch displays an up-count from 1 to 10 in the Serial Monitor
 */

const int startVal = 1;                      // Starting value for counting
const int endVal = 10;                       // Ending value for counting
const int baudRate = 9600;                   // For setting baud rate

void setup()                                 // Built in initialization block
{
  Serial.begin(baudRate);                    // Set data rate to baudRate
 
  for(int i = startVal; i <= endVal; i++)    // Count from startVal to endVal
  {
    Serial.println(i);                       // Display i in Serial Monitor
    delay(500);                              // Pause 0.5 s between values
  }
  Serial.println("All done!");               // Display message when done
}

void loop()                                  // Main loop auto-repeats
{
  // Empty, no repeating code.
}

Documenting Code

Documenting code is the process of writing notes about what each part of the program does. You can help make your code self-documenting by picking variable and constant names that help make the program more self-explanatory.   If you are thinking about working in a field that involves programming, it’s a good habit to start now. Why?

• Folks who write code for a living, like software developers and robotics programmers, are usually under orders to document their code. 
• Other people might need to make updates to your code or use it for another project, and they need to understand what the code does.
• Documented code can save you lots of time trying to remember what your code does,  and how it does it, after you haven’t looked at it for a long time.

In addition to making your code easier to read, constants allow you to adjust an often-used value quickly and accurately by updating a single constant declaration. Trying to find and update each instance of an unnamed value by hand is an easy way to create bugs in your sketch.

• Read through the sketch to see how constants and comments are used.
• Open up the SimpleDecisions sketch and document it, using the sketch CountToTenDocumented as an example.

• Add a detailed description of the sketch, enclosing it with the title in a block comment.
• Use const declarations for the values of 89 and 42.
• Use the names from your const declarations instead of 89 and 42 in the setup function.
• Add line comments to the right of each line.