Comments about Program Structure and Commenting Your Code

Program Structure: Your Code Should Look Like Your Flowchart! Especially Loops!

Your flow chart (your plan for your code) should drive the look/structure of your code (not the other way around!)
Loops on your flow chart should correspond with loops in your code
You should not have overlapping loops on your flowchart as you cannot overlap loops in your code. Loops can...
- Be sequential (e.g., loop two comes after loop 1)
- Be "nested" (e.g., loop 1 contains loop 1(a)). You have many levels of nesting, but be careful--it should follow your plan (flow chart)
The key to loops are the conditional logic tests you use to enter and exit the loops

DO NOT write comments for each line of code, especially if the purpose is obvious. Bad examples:
- cr8_update(cr8); // update Create sensors obviously, so why did you need to tell the reader??
- cr8_drive_direct(150,150); // drive Create straigh forward obviously!!
DO use BRIEF but INFORMATIVE comments to describe blocks or small chunks of code (loops, functions, key blocks of code, etc.) just before the code. Good examples:
- // This loop causes the cr8 to wait for the pay button to be pressed before it executes the main loop. Safety features are also enabled, and the play light blinks on and off for the user to see.
- //Check for left and right bumper ON-- if SO reset odometer and turn in opposite direction -- if NOT blah blah blah ...
- When commenting new functions, tell what the function does, decribe the variable (parameters) passed from/to the calling function, and describe what values are returned
- Be sure to keep the "placeholder comments" that we provide in the template main.c. If you don't use the particular comment (e.g., suppose you don't declare any global variables), keep the comment intact but delete any example we provided, if any.